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When using this document, keep the following in mind: 


1 
2. 


This document may, wholly or partially, be subject to change without notice. 

All rights are reserved: No one is permitted to reproduce or duplicate, in any form, the whole or part of this document 
without Hitachi's permission. 

Hitachi will not be held responsible for any damage to the user that may result from accidents or any other reasons 
during operation of the user's unit according to this document. 

Circuitry and other examples described herein are meant merely to indicate the characteristics and performance of 
Hitachi's semiconductor products. Hitachi assumes no responsibility for any intellectual property claims or other 
problems that may result from applications based on the examples described herein. 

No license is granted by implication or otherwise under any patents or other rights of any third party or Hitachi, Ltd. 
MEDICAL APPLICATIONS: Hitachi's products are not authorized for use in MEDICAL APPLICATIONS without the 
written consent of the appropriate officer of Hitachi's sales company. Such use includes, but is not limited to, use in life 
support systems. Buyers of Hitachi's products are requested to notify the relevant Hitachi sales offices when planning 
to use the products in MEDICAL APPLICATIONS. 
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Editor. 


Preface 


This manual explains how to use the H Series Linkage Editor, version 5 (Ver. 5). 


The nine sections and one appendix of this manual cover the following subject matter: 


Overview 

Linkage Editor Functions 

Executing the Linkage Editor 

Linkage Editor Options and Subcommands 
Input to the Linkage Editor 

Output from the Linkage Editor 

Error Messages 

Restrictions 


Object Format Conversion 


Appendix A Example of Use of Linkage Editor 


Installation of the Linkage Editor is covered in the Installation Guide supplied with the Linkage 
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Users are encouraged to consult the user’s manuals for other programs in the H Series cross- 
software system. Relevant manuals include: 


* H Series Librarian User’s Manual 

* H8/300 Series Cross Assembler User’s Manual 
* H8/500 Series Cross Assembler User’s Manual 
* H32 Series Cross Assembler User’s Manual 

* SH Series Cross Assembler User’s Manual 

* H8/300 Series C Compiler User’s Manual 

e 8/500 Series C Compiler User’s Manual 

¢ H32C Compiler User’s Manual 


* SH Series C Compiler User’s Manual 
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Notes: 


The following symbols have special meaning in this manual 


<item> : <Specification item> 
{ } : One of the items between the brackets is to be selected. 
{ ] : The enclosed item is optional (i.e., can be omitted) 


: The preceding item can be repeated. 
A : Blank space(s) or tab(s) 


: Press the Return (Enter) key. 


UNIX is an operating system administrated by the UNIX System Laboratories (United States). 
MS-DOS is an operating system administrated by the Microsoft Corporation (United States). 
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Section 1 Overview 


The growing need for large-scale, complex microcomputer programs has led to the common 
practice of developing a program in separate parts and using a high-level language. In generating 
a program in this fashion, a compiler or an assembler is used to convert source programs into 
object modules. After that, a linkage editor is employed to link and edit the modules into one load 
module file. 


The H Series Linkage Editor inputs object module files output by an assembler or C compiler, 
links and edits them, and generates a single load module file. 


Figure 1-1 illustrates the program development procedure using the Linkage Editor. 
Assembly- C-language 


language source program 
source program 


Absolute Relocatable 


load module load module 


Load module 
(S-type) 


Note: * The Linkage Editor described in this manual. 


Figure 1-1 Program Development Procedure 
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The linkage editor has the following features: 


(1) Linkage can be executed by command-line specifications or by subcommands. These two 
methods allow flexible control over the Linkage Editor to match the desired application. 


The load module file output by the Linkage Editor can be re-input and re-edited to generate a 
new load module file. 


(2 


pled 


(3) Data used by a simulator/debugger or in-circuit emulator in symbolic debugging can be 
specified for inclusion in the load module file. 


1.1 Linkage Editor Functions 
The Linkage Editor provides the following five basic functions. 


Module Linkage: The module linkage function links and edits object modules output by a 
compiler or assembler. 


Address Resolution: The address resolution function determines absolute addresses for external 
reference symbols so that references can be made between modules. It also determines absolute 
addresses for relative addresses. 


Load Module File Re-input: The re-input function enables a load module file output by the 
Linkage Editor to be input again. 


Multilinkage: The multilinkage function enables the linkage process to be carried out multiple 
times during one execution of the Linkage Editor. 


Debugging Support: The debugging support function allows display of interim linkage results 
and provisional correction of errors. 


1.2 Object Module and Load Module 


An object module is output as a result of compiling or assembling a source program. A load 
module is obtained by using the Linkage Editor to link object modules. 


There are two load module formats: absolute and relocatable. An absolute load module has been 
assigned absolute addresses, and is in executable form. It does not contain relocation information 
for relinking and relocation. A relocatable load module has been assigned relative addresses and 
contains relocation information. This information enables the relocatable load module to be 
re-input into the Linkage Editor for relinking and relocation. The load module format is selected 
by the FORM option or subcommand. For details on the FORM option and subcommand, refer to 
section 4.5.3, “FORM — Specifies Output Load Module File Format.” 
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Object modules, absolute load modules, and relocatable load modules are collectively referred to 
as modules in this manual. 


Modules are either page type or non-page type, depending on the H series microcomputer. The two 
types differ as to the method of assigning addresses when modules are linked. H8/500 Series 
modules are page type, whereas H8/300 Series, H32 Series, and SH Series modules are non-page 
type. When the Linkage Editor is used to link modules, page type and non-page type modules 
may not be linked together. 


1.3 Unit and Section 


A unit in a module refers to a compile unit or assembly unit. An object module output by a 
compiler or assembler consists of a single unit. A load module which represents multiple object 
modules that have been linked by the Linkage Editor contains more than one unit. 


A unit is divided into sections. The Linkage Editor processes one section at a time. 


The interrelation among module, unit, and section is illustrated in figure 1-2. 


Module 


Figure 1-2 Interrelation among Module, Unit, and Section 


A section has a name for identification, an attribute describing its content and usage, and a format: 
either absolute or relocatable. Even if two sections have the same name, they are treated as 
separate sections when their attributes or formats are different. 


Section attributes and formats are classified as follows. 
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(1) Attributes 

* Code: An area containing instructions or constants. 

e Data: A variable area with values that are changed by the program. 
e = Stack: A stack or work area which cannot be initialized. 

+ Common: A variable area used in common by multiple modules. 


+ Dummy: Used, for example, to define the structure of a variable area; does not generate any 
actual object code. 


(2) Formats 


+ Absolute: A section in which absolute addresses have already been assigned. 


* Relocatable: A section in which absolute addresses have not yet been assigned. 
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Section 2 Linkage Editor Functions 


This section gives a more detailed description of the basic functions provided by the Linkage 
Editor. The following discussion and examples will make reference to various options and 
subcommands used to control the Linkage Editor. Additional information on these options and 
subcommands can be found in section 3, “Executing the Linkage Editor,” and section 4, “Linkage 
Editor Options and Subcommands.” 


2.1 Module Linkage 


The Linkage Editor reads modules from specified input files and links these modules to generate 
one load module. Modules are linked by each section, a section being the smallest complete part 
making up a module. 


2.1.1 Section Linkage 


A section is linked only if it is relocatable. Since absolute sections have already been assigned 
absolute addresses, no further linking is performed. Relocatable sections are linked according to 
the procedure described below. 


(1) Grouping of sections with the same name 


Sections having the same name but found in more than one unit are grouped. 


Grouping of sections named A 


P| 

Grouping of sections named B 
| 

Grouping of sections named C 


Figure 2-1 Grouping Sections Having the Same Name 
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A warning message is output when sections have the same name but different attributes. Such 
sections are then processed as separate sections. 


(2) Linking of sections with the same name 
Sections having the same name are linked in one of three ways, depending on their attributes. 
(a) Simple linkage 


Sections with the code, data, or stack attribute and having the same name are allocated 
consecutively, in the order in which the modules were input. 


Unit X Unit Y Linkage of sections named A 


* "> 


Figure 2-2 Simple Linkage 


Section A in 
Unit X 


Section A in 
Unit Y 


(b) Common linkage 


Sections with the common attribute and having the same name are allocated at the same 
address. The address area allocated is equal to the size of the largest section. 


Unit X Unit Y Linkage of sections named B 


| ee 
--- Unit X 


Figure 2-3 Common Linkage 
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EXAMPLE 1 (UNIX system): 


% IbrA-CREATE=syslib.lib-ADD=obj00.obj,prg.lib RET 
HY ———_— 


1 2 


1 Creates a new library file named syslib.lib. 
2 Adds the modules in object module file obj00.obj and library file prg.lib to syslib.lib. 


The CREATE option by itself will not create a library file unless modules are added using the ADD 


option. 
EXAMPLE 2 (MS-DOS system): 
% \brAsyslib.lib/ADD=o0bj00.0bj/DELETE=mod1(RET) 


eee 
1 2 3 


1 Designates library file syslib.lib as the file to be edited. 
2 Adds the module in object module file obj00.obj to syslib.lib. 
3 Deletes existing module mod! from syslib.lib. 


3.3 Executing by Subcommands 


Since the number of characters that can be typed on the command line is limited, the command line 
may not be able to accommodate a large number of specifications. In such cases, subcommands are 
used to execute the Librarian. Subcommands can be input interactively, one at a time, from the 
keyboard or other standard input device. Alternatively, a subcommand file consisting of a group of 
subcommands can be created in advance, and subcommands can be input from this subcommand 
file. 


3.3.1 Executing in Interactive Mode 


When no library file is specified in the command line and there are no option specifications, 
execution proceeds in interactive mode. A colon (:) appears on the screen as a prompt, indicating 
that the Librarian is waiting for a subcommand to be input. In this way you can enter the necessary 
subcommands. This method is useful when the number of subcommands is relatively small, or 
when you want to check Librarian lists as you enter the subcommands. 
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(a) With a specified linkage order 


Unit X Unit Y Unit Z 


Section A Section A: 


i 


Section B Section B: 


Section C Section C Section C: 


Section D Section D Section D: 


ii 
ul 


Section linkage order A—>D—> B 


<— 


Section A (X) 
Section A (Y) 
Section A (Z) 


Section D (X) 
Section D (Y) 


——-_ 
Section B 


code section 


common section 


dummy section 


data section 


Le 


Figure 2-5 Example of Section Linkage with a Specified Linkage Order 
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The section linkage order can be specified only when the load module output by the Linkage 
Editor has the absolute format. The linkage order is specified using the START option or 
subcommand. 


(b) Without a specified linkage order 


Section A: data section 


Section B: common section 


[ Section ¢ | Section C: dummy section 
Section D: code section 


I Sections are input in the order © through @ 


Section A (X) 


Section A (Y) 
Section A (Z) 


Section D (Z) 


Figure 2-6 Example of Section Linkage without a Specified Linkage Order 
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Sections having the same name but different attributes are linked in the order in which they are 
input. 


Unit X Unit Y Unit Z 


Section A Section A Section A 
<data> <stack> <code> 


Sections are input in the order of @ through @ 


Section A (X) 
<data> 


Section A (Y) 
<stack> 


Section A (Z) 
<code> 


Figure 2-7 Example of Section Linkage for Same Section Name but Different Attributes 


(4) Address assignment 


Addresses are assigned to each section. Absolute.addresses are assigned when the output load 
module. file has the absolute format. The section linkage order and start address can be specified 
using the START option or subcommand. Absolute addresses are assigned to each section in 
order, beginning with the start address. If no start address is specified, absolute addresses are 
assigned beginning from address zero. 


If sections with absolute format are linked to sections with relocatable format, the same absolute 


address may be assigned to more than one section. In that case, the Linkage Editor displays a 
warming message. 


10 


HITACHI 


When page type modules are linked, if addresses are assigned section by section, one section may 
overlap a page boundary. In this case the Linkage Editor will display a warning message. 
However, executing a load module one of whose sections overlaps a page boundary is extremely 
troublesome. For this reason the Linkage Editor is provided with an autopaging function, which 
prevents any section in a unit from overlapping the page boundary by allocating the section to the 
top of the next page. Use of this function is designated by means of the AUTOPAGE option or 
subcommand. The different methods of assigning addresses to page type modules are shown in 
figure 2-8 (neither autopaging nor start address specified), figure 2-9 (autopaging specified, start 
address not specified), and figure 2-10 (autopaging and start address specified). 


When the output load module file has the relocatable format, addresses in each section are 


assigned relative to the beginning of the section. The output format is specified using the FORM 
option or subcommand. 
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Section A: code section 


Section B: common section 


Section C: dum _..y section 


Section D: data section 


Page boundary —= Section A in Unit Z 


overlaps page boundary 


Section D in Unit X 


Page boundary —> F overlaps page boundary 


Section D in Unit Y 


Page boundary E overlaps page boundary 


Figure 2-8 Linking of Page Type Modules 
(Neither Autopaging nor Start Address Specified) 
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Page boundary —= 


Page boundary —= 


Page boundary —= 


Page boundary —= 


Section A: code section 
Section B: common section 
Section C: dummy section 


Section D: data section 


Section linkage order specified as: A->D +B 


Section A (X) 
Section A (Y) 


Section A (Z) 


Figure 2-9 Linking of Page Type Modules 
(Autopaging Specified, Start Address Not Specified) 
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Section A: code section 
Section B: common section 


Section C: dummy section 


Section D: data section 


Section linkage order specified as: A—> D-— B 


Startaddress —+}------------- 
Section A (X) 


Section A (Y) 


Page boundary —= 


Page boundary —= 


Page boundary 


Page boundary —= 


Page boundary 


Figure 2-10 Linking of Page Type Modules (Autopaging and Start Address Specified) 
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2.1.2 Inclusion from Library Files 


The Linkage Editor can link object modules and relocatable load modules input from library files 
created with the H Series Librarian, and include these modules in the output load module. 
Inclusion from library files can be accomplished in either of the following two ways. 


(1) Inclusion by Specifying the Module Name: Particular modules in a library file can be 
included by specifying the library file name and module name when input file names are 
specified. Input file names are specified on the command line or by the INPUT subcommand. 


(2 


~~ 


Automatic Inclusion: After all specified modules have been input, the Linkage Editor 
begins resolving external reference symbols (after this, external reference symbol is called 
“import symbol”). If an import symbol is not defined in any of the modules, the Linkage 
Editor searches the specified library files. If it finds a module defining the unresolved import 
symbol, the Linkage Editor automatically inputs and links this module. If the unresolved 
import symbol is not defined in any of these library files, the Linkage Editor searches one or 
more default library files defined in advance by the user. Again, if it finds a module defining 
the unresolved import symbol, the Linkage Editor automatically inputs and links this module. 


’ 


If no module in the default libraries defines the unresolved import symbol, an undefined import 
symbol error occurs. 


A detailed explanation of default libraries is given in section 5.4, “Default Library Files.” 


Library files are classified into system library files and user library files. The Linkage Editor first 
searches user library files. When modules containing externally defined symbols (after this, 
externally defined symbol is called “export symbol”) of the same name exist both in a specified 
system library file and in a user library file, the module in the user library file is linked. The order 
in which two or more user library files or system library files are searched depends on the order in 
which they are specified. 


For a library file can contain both page type and non-page type modules. If both types of modules 
are input into the Linkage Editor at the same time, an error will occur. Care must therefore be 
taken both when creating library files and when specifying them. 


Library files are specified using the LIBRARY option or subcommand. On the designation of 
library files as system files or user files, see the H Series Librarian User’s Manual. 


An example of the order of module linking when library files are specified is given below. 
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(1) Object modules a and b are input by the INPUT subcommand. 


Module a Module b 


.IMPORT X1, Z1 -IMPORT X2, Y2 
MOV @X1, RO MOV @xz2, RO 


MOV @2Z1, Ri MOV @Y2, R1 


Figure 2-11 Example of Module Linking (Input Object Modules) 


(2) Library files lib1, lib2, and lib3 are input in that order by the LIBRARY subcommand. 


Library lib1 Library lib2 Library lib3 


Module 10 Module 20 Module 30 
-EXPORT X2 -EXPORT Y1 .EXPORT Z1 


Module 11 Module 21 Module 31 
-EXPORT X1 -EXPORT Y2 -EXPORT Z2 


Figure 2-12 Example of Module Linking (Input Library Files) 


(3) The Linkage Editor first collects all import symbols declared in the input files, then searches 
for export symbols in the first specified library. If a symbol is found, the module defining it 
is linked. 


If two or more symbols are declared in separate modules in the same library, the modules are 
linked in their order of appearance in the library. If a symbol is not found in that library, the 
next specified library is searched. 


In the above example, modules are linked in the following order. 
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Module b 
Module 10 


Module 11 
Module 21 
Module 30 


Figure 2-13 Example of Module Linking (Output Load Module) 


2.1.3 Exclusion of Module Linking 


An option or subcommand can be used to select whether or not to link modules that define non- 
referenced import symbols. In the following coding example symbol abc is declared as an import 
symbol, but is not referenced in any executable statement. If exclusion is specified, the module 
defining symbol abc in a library file will not be linked. 


-IMPORT xyz, abc 
MOV.W @xyz, RO 


-END 


Figure 2-14 Example of Module Containing Non-Referenced Import Symbol 


In a C-language program, import symbols are described by an extern declaration, but these 
symbols are not necessarily referenced. (For example, a large number of non-referenced import 
symbols are declared in stdio.h.) The exclusion function can reduce program size by excluding 
unnecessary modules. Exclusion of such modules is specified by the EXCLUDE option or 
subcommand. 
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2.2 Address Resolution 
When a source program is assembled, the absolute addresses of certain symbols cannot be 
decided. These include symbols imported from another module and symbols in relocatable 


sections of the same module. The Linkage Editor determines absolute addresses for these 
symbols and sets the absolute addresses to the reference positions. 


2.2.1 Import Symbol Resolution 


When importing symbols from a separate module, the assembler outputs import information in the 
object program. It also declares export of symbols that can be imported in other modules. Asa 
result, export information is output in the object program. The Linkage Editor relates this import 
and export information. In addition, it uses address information specified by options or 
subcommands to determine absolute addresses for the export symbols, and replaces corresponding 
import symbols with the absolute addresses. 


The example given in figure 2-15 illustrates how import symbols are resolved. The modules, 
sections, and subcommands used in the figure are explained below. 


(1) Module a 

* This module consists of one section, section X, having a size of 5000 (hexadecimal) bytes. 
* Symbol S4 in module b is imported at position Al. 

* Symbol S2 in module b is imported at position A2. 

(2) Module b 

* This module consists of sections X and Y. 

* The size of section X is 2000 (hexadecimal) bytes. 

* The size of section Y is 3000 (hexadecimal) bytes. 

° $1 is the start of section Y. $2 is located 1000 (hexadecimal) bytes from S1. 

e §3 is the start of section X. S4 is located 1200 (hexadecimal) bytes from S3. 

(3) Module c 

* This module consists of one section, section Z, having a size of 4000 (hexadecimal) bytes. 
¢ Symbol S3 in module b is imported at position C1. 


¢ Symbol S1 in module b is imported at position C2. 
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(4) Subcommands 


INPUTAa, b, c 
STARTAX, Y, Z(10000) 


EXIT 


Three modules a, b, and c are input to the Linkage Editor. Sections are linked in the order X, Y, Z. 
The start address is 10000 (hexadecimal). 


5000 bytes 
(hexadecimal) 


Module b 


Ea eer eee 


3000 bytes 
(hexadecimal) 


2000 bytes 
(hexadecimal) 


Absolute address of S1: 17000 (hexadecimal) 
Absolute address of S2: 18000 (hexadecimal) 
Absolute address of S3: 15000 (hexadecimal) 
Absolute address of S4: 16200 (hexadecimal) 


Set 16200 (hexadecimal) to position A1. 
Set 18000 (hexadecimal) to position A2. 
Set 15000 (hexadecimal) to position C1. 
Set 17000 (hexadecimal) to position C2. 


4000 bytes 
(hexadecimal) 


Figure 2-15 Resolution of Import Symbols 
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When a symbol defined in a relocatable section of a module is referenced within the same module, 
the assembler expresses the symbol address as a relative address from the start of the section. The 
Linkage Editor uses this relative address value and address information specified by options or. 
subcommands to decide the absolute address. It then replaces the relative address with the 
absolute addresses. 


The example given in figure 2-16 illustrates the resolution of addresses within a module. The 
modules, sections, and subcomiaands used in the figure are explained below. 


(1) Module a 

¢ This module consists of one section, section X, having a size of 5000 (hexadecimal) bytes. 
(2) Module b 

¢ This module consists of sections X, Y, and Z. 

* The size of the section X is 6000 (hexadecimal) bytes. 

e The size of the section Y is 1000 (hexadecimal) bytes. 

¢ The size of the section Z is 2000 (hexadecimal) bytes. 

* Bl references $1. 

« B2references $3. 

° B3 references S2. 

* $1 is located 3000 (hexadecimal) bytes from the start of section X. 
* §2 is located 4500 (hexadecimal) bytes from the start of section X. 
e §3 is located 5000 (hexadecimal) bytes from the start of section X. 


(3) Subcommands 


INPUTAa, b 
STARTAX, Y, Z(10000) 


EXIT 
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Two modules a and b are input to the Linkage Editor. Sections are linked in the order X, YZ. 
The start address is 10000 (hexadecimal). 


5000 bytes 
(hexadecimal) 


Module b 


| 1000 bytes 
J (hexadecimal) 


6000 bytes 
(hexadecimal) 


2000 bytes 
(hexadecimal) 


Logical address of S1: 18000 (hexadecimal) 
Logical address of S2: 19500 (hexadecimal) 
Logical address of S3: 1A000 (hexadecimal) 


Set 18000 (hexadecimal) to position B1. 
Set 1A000 (hexadecimal) to position B2. 
Set 19500 (hexadecimal) to position B3. 


Figure 2-16 Address Resolution within a Module 
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2.2.3 Suppressing the Listing of Unresolved Symbols 


For a relocatable load module, the display of unresolved symbol names can be suppressed. This 
can be selected by the UDF option or subcommand. 


2.3 Load Module File Re-Input 


Load module files have to be recreated using the Linkage Editor when a program has been 
modified or import symbols remain unresolved. The re-input function eliminates the need to 
specify each object module separately. By simply specifying the existing load module file and the 
object module files that were modified (or the object module files containing the export symbols), 
this function will recreate the load module file. 


. 


If modules are to be replaced, the re-input function carries out the replacement on a unit basis. A 
detailed explanation of unit replacement is given in section 2.3.1, “Automatic Unit Exchange.” 


The load module file to be re-input can be specified on the command line or using the INPUT 
subcommand. 


Only load module files in relocatable format can be re-input. The FORM option or subcommand 
is used to specify the relocatable format when creating a load module file. 


An overview of the load module file re-input function is shown in figure 2-17. 
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Load module file a 


[ Unit Ut | Load module file d 


Object module file b 


Linkage 
editor 


Object module file c 


Figure 2-17 Load Module File Re-Input Function 


Load module file a and object module files b and c are input to the Linkage Editor, which outputs 
a new load module file d. Load module file d consists of units U1, U2, U3, U4, US, and U6. 


2.3.1 Automatic Unit Exchange 


When the Linkage Editor finds units with the same name in two or more modules, it gives 
inclusion priority to the unit in the module that was specified first. To replace units in a load 
module file, first specify files containing the replacement units, then specify the relevant load 
module file. This will produce the same result as using the EXCHANGE subcommand. This 
function is called automatic unit exchange. 


By using automatic unit exchange, new load module files can be created by simply changing the 
specified order of file input. This feature is convenient when it is necessary to modify programs 
frequently, such as during debugging. 


An example of the procedure for automatic unit exchange is shown in figure 2-18. 
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Subcommand contents 


(1) Automatic ; 
exchange Load module file d 


INPUT Ac, b, a 
OUTPUT Ad 


Load module file a 


é Unit U2‘: 


(2) No automatic 


exchange Load module file d 


“= INPUT da, b,c 
“=, OUTPUT Ad 


See reer te BT, pec emenwcccecees! 


Figure 2-18 Automatic Unit Exchange 


(1) Automatic Exchange: Object module files c and b and load module file a are input in that 
order. Unit U2 in load module file a is not included by the Linkage Editor since unit U2 in 
load module file c has already been input. 


(2) No Automatic Exchange: Load module file a and object module files b and c are input in 
that order. Unit U2 in load module file c is not included by the Linkage Editor since unit U2 
in load module file a has already been input. 
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2.3.2 Forced Unit Exchange 


In addition to using automatic unit exchange, the EXCHANGE subcommand can also be 
employed to specify the units to be replaced. This function is called forced unit exchange. 


By specifying the following subcommands, the result of forced unit exchange will be the same as 
that of the automatic unit exchange shown in figure 2-18. 


Forced unit exchange Automatic unit exchange 


INPUT A a, b INPUT Ac, b, a 
EXCHANGE Ac OUTPUT Ad 


OUTPUT Ad 


In this example of forced unit exchange, the Linkage Editor inputs units U1, U2, U3, and U4 in 
load module file a and unit US in object module file b, then forcibly replaces the unit U2 already 
input with unit U2 in object module file c. Load module file d output by the Linkage Editor 
contains units U1, U3, and U4 from file a, unit U5 from file b, and unit U2 from file c. Thus load 
module file d has the same unit configuration as load module file d shown in the example of 
automatic file exchange in figure 2-18. 


2.4 Multilinkage 


The Linkage Editor can handle up to 256 input files in one linkage process. When there are 
multiple input files, one way to link them is to re-input the load module file. The multilinkage 
function allows several linkage processes to be completed with just one execution of the Linkage 
Editor, instead of executing it separately for each linkage process. 


The END subcommand indicates the end of one linkage process when multilinkage is performed. 
The end of the final linkage process, however, is specified by the EXIT subcommand. 


An example of a multilinkage operation is shown in figure 2-19. 
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Input files Subcommand contents 
¥ gt INPUTAifile1 
!INPUTAifilen 


n files ' 


Relocatable 
load module file 


ve — PINPUTAImt.rel; 
ee: INPUTAtfle n+ | 
m files : INPUTA file 5 
| OUTPUTS im2 ‘ Relocatable 
om ; FORM4R —_ module file 


: END 
aeeavnee pee retai goes Im2 
eae PINPUTAIm2.r6l ue 
_— INPUTAifile mst 
Tie ‘ ' : INPUTS file ° : see sites 
‘ OUTPUTA Im3 moe 


A er ae eee {ne 


+ indicates one 
linkage process 


Note: When the default library is used during multi-linkage process, the modules in the 
default library are linked in the first linkage process. When the modules must be 
linked in the final linkage process, specify the NOLIBRARY command in the 
processes except the final process. 


Figure 2-19 Miultilinkage Function 
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2.5 Debugging Support 


Debugging support functions are used to confirm the interim linkage results at the program 
debugging stage and to make provisional recovery from errors in load module files. Debugging 
support functions include displaying interim linkage information as well as defining, changing, 
and deleting export and import symbol names. A brief explanation of each function is given 
below. 


(1) 


(2 


~ 


G3) 


Display of Interim Linkage Information: This function is used during subcommand input 
when it is desired to see information about the load module being processed by the Linkage 
Editor. Specifying the LIST subcommand outputs interim linkage information to the standard 
output device. 


Three types of linkage information are displayed. 
(a) Linkage map 

(b) Unresolved import symbols 

(c) Export symbols 


Change and Deletion of Unit Names, Export Symbol Names, and Import Symbol Names: 
These functions make it possible to change or delete any duplicated names of units, export 
symbols, and import symbols. Noted that names of import symbols cannot be deleted. 


Names are changed by the RENAME subcommand and are deleted by the DELETE 
subcommand. 


Forced Definition of Import Symbols: This function is used to define provisional values 
for import symbols. The values defined with this function are valid only for the linkage 
operation being processed. 


The forced definition of these symbol values is specified using the DEFINE option or 
subcommand. 
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2.6 Address Check 


When an absolute load module is created with the Linkage Editor, addresses must be assigned to 
sections in accordance with the target CPU memory map. If not, the load module cannot be 
loaded to memory. 


The address check function provided with the Linkage Editor confirms the validity of section 
address assignments on the basis of CPU memory map information (hereinafter called “CPU 
information”). This CPU information is read from a specified file. 


To execute an address check, the CPU option or subcommand is used to specify the CPU 
information file. The CPU information file is created using the CPU information analysis 


program (CIA) included in the H8/300 series Simulator/Debugger. Note that the CPU information 


analysis program is not available for CPUs other than the H8/300 and SH series; thus the address 
check function can be used only with this series. 


Regarding the method of creating a CPU information file, refer to the H8/300 Series or SH Series 
Simulator/ Debugger User’s Manual or the SH Series Simulator/Debugger User’s Manual. 


2.7 Support of Storing Program in ROM 
When a user program is coded in C language and the load module is to be stored in ROM, data 


sections having initial value (D sections) will also be stored in ROM. To assist the user, the 
Linkage Editor carry out the following operations. 
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(1) An area of the same size as the D section (called the D' section) is reserved in the RAM area 
of the output load module. The memory map of the load module looks like this: 


Program area 


Initialized data area (D) | 


Se 


Non-initialized data 
variable area (B) 


wesz Area reserved for data having initial value 


Figure 2-20 Memory Map for Storing Program in ROM 


(2) When a variable declared in the D section is referenced, its address is changed to point to the 
RAM area. The variable address becomes: 


Starting address of D section + relative address within section 
The ROM ability support function changes this to: 

Starting address of D’ section + relative address within section 
Example: MOV @a, RO 


The address of symbol “a” declared in the D section becomes (x) + (y) as shown below. This 
address is also stored on the object code. 


Starting address 


of D section Relative address 
within section (y) 


mr Simba 


Starting address 


of D’ section (x) Relative address 
within section (y) 


| ned 


Figure 2-21 Symbol Address for Storing Program in ROM 
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(3) Data is copied from ROM to RAM in the start-up routine. 
The copy process is included in the start-up routine. The procedure for including this process 
is described in the C Compiler User’s Manual. 
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Section 3 Executing the Linkage Editor 


To execute the Linkage Editor, first starts Linkage Editor by entering a command line. This 
command line specifies the names of files to be input, and also specifies options giving various 
instructions to the Linkage Editor. If these instructions are sufficient, the Linkage Editor can be 
executed using the command line alone. If further instruction are needed, they can be given in 
subcommands. 


Command Line Specification: This method executes linkage simply by specifying the input 
files and options on the command line. It is used when only a few files are to be input and the 
linkage operation is relatively straightforward. 


Specifying Subcommands: This method, in addition to a command line, uses subcommands to 
control the Linkage Editor. The subcommands specify files to be input and output, and execution 
control parameters for the Linkage Editor. This method is used when a large number of files or 
modules are specified, when the order in which sections are to be linked specified, or when 
multilinkage function is used. There are two ways of specifying subcommands: One is direct 
input from the keyboard or other input device in interactive mode and the other is input from a 
subcommand file. 


UNIX System: File names are specified in the following format: 


path name main filename _ file type 
0) ® @ 
@ Path name 


Specify the directory path of the directory containing the file, using slashes (/) to delimit 
directory names. The default value is the current directory. 


@ Main file name 
Specify the name of the file. 


@ File type 
Specify the type of file separated from the main file name by a period (.). 


The general rules of file naming for the Linkage Editor conform to the operating-system (OS) rules. 


The OS shell (command interpreter) checks the command line before passing control to the 
Linkage Editor. Use characters that the OS allows on the command line. 


Example: /ust/tool/prog.typ 
t A____rits type 
Main file name 
Path name 
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PC System: Before using this Linkage Editor, set the MS-DOS configuration file 
(CONFIG.SYS) with the editor as follows. 


FILES=20 
| SHELL=a:¥command.com a:¥ /p 


® The number of files that is allowed to open at one time during Linkage Editor operation. 
@ Directory path specification that is required when COMMAND.COM is re-loaded. 


If both the input file and the output file have the same name, the input file data will be damaged. 


Take care that the input and output files do not have the same name. 


3.1 Command Line Format 


The following format is used for the Linkage Editor command line. 
UNIX System: 


lnkA [<input file name>[,<input file name>]...] 
[[A]-<option name>[[A]—<option name>...]] 


PC System: 


LNK [<input file name>[(<module name>[,<module name>...])] 
{,<input file name>[(<module name>[,<module name>...])]]...] 
[[A]/<option name>[[A]/<option name>...]] 


(1) Command Name: “Ink” is input to start up the Linkage Editor. 


(2) Input File Names: Names of files to be input in the Linkage Editor are specified. These 
may be object module files or relocatable load module files. When more than one file is 
specified, the names are delimited by a comma (,). 


If the file type is not specified with the input file name, the Linkage Editor automatically 
assumes that the type is “.obj.” In MS-DOS system, up to 256 files can be input in one 
linkage process. However the maximum number of characters that can be input in a line is 
255, and therefore 256 files can not be specified in one line. When many files must be 
specified, use the subcommand. 


(3) Module Name (Only for PC System): When the library file is specified as the input file, 
specify the module name. The module name must be preceded by the library file name and 
must be specified in the parentheses. If the input file is the object module file or the load 
module file, do not specify the module name. 
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(4) Option Names; Each option name must be preceded by a hyphen (-). When an option name 
follows an input file name or another option name, one or more spaces or tabs may be 
inserted to delimit the names, or they may be entered continuously. Option names are 
described in detail in section 4, “Linkage Editor Options and Subcommands.” 


(5) Specifying the Mode of Execution: Command line specification determines whether 
linkage is to be executed by the command line only or subcommands are to be used as well. 


(a) Specifying execution by command line: If one or more input files are specified on the 
command line and no subcommand file is specified, module linkage will be executed 
according to the command line only. 


(b) Specifying subcommands: If no input files are specified on the command line, or a 
subcommand file is specified, control of the Linkage Editor will be controlled by the 
subcommands. 


3.2 Executing by Command Line 


In this method, input files are specified on the command line, and the Linkage Editor executes 
module linkage according to the information specified in the command line alone. Output files 
and other instructions to the Linkage Editor are specified in the form of options. Command line 
execution is sufficient for performing linkage operations when the number of input files is small, 
and when there is no need for detailed instructions to the Linkage Editor such as regarding the 
order in which sections are to be linked. Examples of execution by command line only are given 
below. For details on options in these examples, see section 4, “Linkage Editor Options and 
Subcommands.” 


EXAMPLE 1 (UNIX system): 
%lnkAadd, sub, ml, divA-OUTPUT=arithA-ENTRY=main 


Four files “add.obj,” “sub.obj,” “mul.obj,” and “div.obj” are to be input to the Linkage Editor. 
These are to be linked and output as absolute load module file “arith.abs.” Export symbol “main” 
is specified as the start address for execution of the output load module file. No linkage list is to 
be output. 


EXAMPLE 2 (MS-DOS system): 
>LNKAMAIN, KEY, DISPLAY, PRINT /OUTPUT=CALC/PRINT=CALC /FORM=R/ DEBUG 


Four files “MAIN.OBJ,” “KEY.OBJ,” “DISPLAY.OBJ;” and “PRINT.OBJ” are to be input to the 

Linkage Editor. These are to be linked and output as relocatable load module file “CALC.REL.” 

Debugging information is to be incorporated in this load module file. Linkage list “CALC.MAP” 
is to be output. 
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3.3 Controlling by Subcommands 


When a large number of files or modules must be input, or when complex section linking is to be 
performed, the command line alone may not be sufficient to contain all the specifications. In such 
cases, subcommands are used to control the Linkage Editor. Subcommands may be entered one at 
a time in interactive mode, from the keyboard or other standard input device, or a subcommand 
file consisting of a group of subcommands may be created in advance, and subcommands may be 
entered from this subcommand file. 


(1) Interactive Mode: Can be used when the number of subcommands is relatively small. This 
method is also useful when the Linkage Editor is employed during program debugging, where 
it is desired to check interim linkage results or make provisional recovery from errors. 


(2) Subcommand File: A subcommand file is used to control the Linkage Editor when the 
number of subcommands is large, or the procedures to be carried out are mostly routine. 
A subcommand file is used by specifying the SUBCOMMAND option on the command line. 
The name of the subcommand file to be input is specified as a parameter of the 
SUBCOMMAND option. 


The Linkage Editor can use a subcommand file even when subcommands are input 
interactively. Specify the SUBCOMMAND subcommand with the subcommand file name as 
a parameter. 


Note: In PC system, input all command lines and subcommand lincs by capital letters. 
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3.3.1 Executing in Interactive Mode 


In this method, subcommands required for Linkage Editor operations are input directly from the 
standard input device. Execution proceeds by this method when no input files are specified on the 
command line and the SUBCOMMAND option is not specified. It is used when the number of 
subcommands to be input is relatively small, or when it is desired to confirm linkage results while 
inputting subcommands, as in the first stage of program debugging. When the debugging support 
function is used, this method of execution is the most suitable. 


An example showing input of subcommands in interactive mode is given below. Functions of the 
subcommands listed here are detailed in section 4, “Linkage Editor Options and Subcommands.” 


EXAMPLE: 
# Ink (RED) .- ec cnne cece cnncesiecenceee 0) 
: INPUTAmain (RET) ----.--------+--++++-- @ 


: INPUTAsend, receive, exchange ...@ 
: INPUTAaccount (RET) .....-------+++++- @ 


: LIBRARYAsyslib (RET .---.---------+++-- ©) 
2 RRINA # (CRED) acucacenedemewemmemenes © 
: FORMAR (RET) .-....--2eceee esse eeeoees 0) 
BME (CRED) nvnnaddnendivctienmincnecnene 
@ Command line, starting up the Linkage Editor in interactive mode. 
@® Inputs object module file “main.obj.” 
@® Inputs three object module files “send.obj,” “receive.obj,” and “exchange.obj.” 
® Inputs object module file “account.obj.” 
© Inputs library file “syslib.lib.” 
© Outputs linkage list to standard output device. 
@ Creates a load module in relocatable format. 
Outputs load module file “main.rel” and ends the linkage operation. 
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3.3.2 Executing from a Subcommand File 


In this method, a subcommand file is used which has been created in advance and which contains 
the subcommands necessary for Linkage Editor operations. This subcomman4d file is specified as 
a parameter of the SUBCOMMAND option or subcommand. This method is used when the 
number of subcommands to be specified is large, or the same linkage process is carried out 
repeatedly routine. It saves trouble to input subcommands from the keyboard each time. 


A subcommand file is created using an editor. An example of executing from a subcommand file 
is given below. Functions of the subcommands listed here are detailed in section 4, “Linkage 
Editor Options and Subcommands.” 


EXAMPLE 1 (UNIX system): 


%1nkA-SUBCOMMAND=prgink.sub (RED ...... ® 
Contents of subcommand file “prgink.sub”: 


OUPPUTAL NGt26n torss eererssewisiseewmeucizwved @ 
ENPUTASIN; COS EAN eis 65.55 -iesarmieinvernierwvaverewwrsre ® 
INEUTAasin ACOs Aten swiescrccaisareewsicts sierete sx ® 
INPUTAhsin, hcos, htan ...50.....ccccceccee ® 
INPUTAlog, 10g10.. 1.2.22. e eee eee ee aee © 
EORMAAS. d.scwinmscnctnnse sep sosossieuen Suned @ 
ERD oo ewresseecouveseweese sand aeace soasee 


® Command line, Starting up the Linkage Editor and entering subcommands from subcommand 
file “prgink.sub.” 


@ Names the output file as “function.” Either “.rel” or “.abs” is assumed, because the file type 
is omitted. 


Inputs object module files “‘sin.obj,” “cos.obj,” and “‘tan.obj.” 
Inputs object module files “asin.obj,” “acos.obj,” and “atan.obj.” 
Inputs object module files “‘hsin.obj,” “hcos.obj,” and “htan.obj.” 


Inputs object module files “log.obj” and “log10.obj.” 


2 ® ©®@ © © 


Creates a load module in absolute format. The file type for the output file name becomes 
“abs.” 


© 


Outputs load module file “function.abs” and ends the linkage operation. 
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EXAMPLE 2: 
Blnk (RET) ove eee eee eee ee eee ee eens ® 
: SUBCOMMAND pgmlnk.sub (RET ---------- @ 


@ Command line, starting up the Linkage Editor. Module linkage is executed interactively, 
because no parameters are specified. 


® Inputs subcommands from “pgmink.sub.” 


If there is no EXIT subcommand in the subcommand file, the Linkage Editor waits for further 
subcommand input. 


3.4 Linkage Editor Termination 


When terminated, the Linkage Editor returns an error level to the system as a return code. 
Execution of a command file can be controlled by this return code. 


The return code has the following values, depending on the error level. 


Normal termination 0 
Warning 0 
Error 1 
Fatal error 1 
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Section4 Linkage Editor Options and Subcommands 


Options and subcommands specify file names and give the Linkage Editor various instructions, 
such as the order in which sections are to be linked. Options and subcommands have four types of 
functions: File control, memory allocation, execution control, and debugging support. These 
functions may be used independently or in combination to cdit load modules in various ways. 


(1) File Control Functions: File control functions specifics input files and output files to the 
Linkage Editor. Input files include object module files, relocatable load module files and 
library files. Output files are load module files and list files. 


(2) Memory Allocation Functions: Memory allocation functions can tell the Linkage Editor the 
order in which sections are to be linked and give their starting addresses. They can also 
specify the address at which the output load module is to start executing. These functions are 
used to change the order in which sections are linked, or to create a load module that is to 
execute from a specified address. 


(3 


~S 


Execution Control Functions: Execution control functions specify the form in which the 
Linkage Editor is to input and output information, and end Linkage Editor operations. These 
are used to input subcommands from a subcomman4d file, or to incorporate debugging 
information in a load module. 


(4 
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Debugging Support Functions: Debugging support functions display contents of a load 
module during a linkage operation, or change information such as export and import symbol 
names, etc. These are useful at the program debugging stage, for confirming interim linkage 
results, or for provisional recovery from errors. 


Options and subcommands have the same names and have equivalent functions, but are specified 
using different formats. Moreover, there are some specifications which can be made only with 
either subcommands or options. Section 4.1, “Option and Subcommand Formats,” and section 
4.2, “List of Options and Subcommands,” should accordingly be read carefully. 


For details on the functions and means of specifying each option and subcommand, refer to 
sections 4.3, “File Control,” through 4.6, “Debugging Support.” 
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4.1 Option and Subcommand Formats 


Each option or subcommand consists of a name and parameters, which together must not exceed 
255 characters. 


(1) Option and Subcommand Structure: 


(a) Name: The name part gives the name of the option or subcommand. For details, see 
section 4.2, “List of Options and Subcommands.” 


(b) Parameters: The parameter part gives information such as the name of files on which the 
option or subcommand operates, and address values. There are different requirements 
and methods of specification depending on the option or subcommand. See sections 4.3, 
“File Control,” 4.4, “Memory Allocation,” 4.5, “Excution Control,” and 
4.6, “Debugging Support.” 


Options and subcommands differ as to the way of separating the name from the 
parameters. Options use an equals sign (=), while subcommands use one or more spaces 
or tabs. 


Option format 


<Name>=<parameters> 


Subcommand format 


<Name>A<parameters> 


EXAMPLES: 
=QUTPUT=LOAGE oie sie wsisee sais eeieis «5 option 
OUTPOPALGREE aisicis assisie oe winianien eee subcommand 


In these examples, “OUTPUT” is the name, and “loadf” is the parameter. 


(2) Continuation Specification for a Subcommand: When a subcommand is too long to be 
specified on one line, a continuation specifier is used. This is an ampersand (&) at the end of 
the line. It must always be placed in between two parameters; if it is placed within a 
parameter, it will be interpreted as part of the parameter. If a character (other than a space or 
tab) is typed after the ampersand, an error will occur and the subcommand will not be 
continued. 


If continuation is specified in interactive mode, a hyphen (-) appears as a prompt for further 
input. 
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EXAMPLES: 


:INPUTA obj00, lib(mod0,mod1) , & 
-obj01, 0b302 

Continuation specifier 
:INPUTA 0bj00, lib(mod0,mod1) , ob& 


te Processed under the file name ob& due 
Not a continuation line to specification within parameter 


(3) Specifying Comments in a Subcommand File: A comment specifier is used when it is to 
add notes or other comments in a subcommand file. The specifier is a semicolon (;) placed 
on a subcommand line, indicating that the rest of the line is acomment. At least one space or 
tab must set off the semicolon from the subcommand name or parameter. 


When a semicolon is placed at the beginning of a subcommand line, the entire line is taken as 
a comment. 


EXAMPLES: 


; EXAMPLE OF LINKAGE SUBCOMMAND 
evaiuwines The entire line is a comment. 


LIBRARYAsyslibA; INDICATES LIBRARY FILE 
anependns “INDICATES LIBRARY FILE” is a comment. 


INPUTAobject .rel; abe 
deisevsssats “object.rel;abc” is treated as one parameter. 
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4.2 List of Options and Subcommands 
There are 15 options and 23 subcommands. The options and subcommands are listed in table 4-1. 
Options and subcommands may be written either in upper-case or lower-case letters. 


Table 4-1 List of Options and Subcommands 


Option/ , Sub- 
No. Type Subcommand Name Function Option command Section 
1 File INPUT Specifies input file No Yes 4.3.1 
control“ QUTPUT* (NOOUTPUT) Specifies output file Yes Yes 4.3.2 
LIBRARY (NOLIBRARY)* Specifies library file Yes Yes 4.3.3 
PRINT (NOPRINT)* Specifies list file Yes Yes 4.3.4 
EXCLUDE (NOEXCLUDE)* Excludes modules from Yes Yes 4.3.5 
linking 
2 Memory START Specifies section starting Yes Yes 4.4.1 
allocation address and linking order 
ENTRY Specifies execution Yes Yes 4.4.2 
start address 
AUTOPAGE (NOAUTOPAGE)* Specifies automatic paging —_ Yes Yes 4.4.3 
CPU Specifies address check Yes Yes 44.4 
ROM Specifies support of storing Yes Yes 4.45 
program in ROM 
3 Execution EXCHANGE Substitutes units No Yes 45.1 
control“ SUBCOMMAND Specifies subcommandfile Yes Yes 45.2 
FORM Specifies format of output Yes Yes 45.3 
load module file 
DEBUG (NODEBUG)* Specifies output of Yes Yes 4.5.4 
debugging information 
ND Terminates subcommand No Yes 45.5 
input 
EXIT Terminates linkage operation No Yes 4.5.6 
ABORT Aborts linkage operation No Yes 45.7 
ECHO* (NOECHO) Specifies subcommand file Yes Yes 4.5.8 
echo-back : 
UDF* (NOUDF) Specifies display of Yes Yes 45.9 
undefined symbols 


Notes: 1. The shortest permissible abbreviated forms are underlined. 
2. Yes and No in the table indicate whether an itemi can be used as an option or subcommand. 
3. An asterisk indicates the default option or subcommand. 
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Table 4-1 List of Options and Subcommands (cont) 


No. 


4 


Option/ Sub- 
Type Subcommand Name Function Option command Section 
Debugging LIST Displays interim linkage No Yes 4.6.1 
support information 
RENAME Changes name of unit, No Yes 4.6.2 
export symbol, or import 
symbol 
DELETE Deletes unit or export No Yes 4.6.3 
symbol 
DEFINE Forcibly defines import Yes Yes 4.6.4 
symbol 


Notes: 1. The shortest permissible abbreviated forms are underlined. 


(1) 


(2) 


2. Yes and No in the table indicate whether an item can be used as an option or subcommand. 
3. An asterisk indicates the default option or subcommand. 


Negative Form of Options and Subcommands: For some options and subcommands a 
negative form starting with “NO” may be specified. Parameters cannot be specified with 
negative-form options and subcommand. There are eight negative option/subcommand 
forms, as follows: 


(a) NOOUTPUT............... Suppresses output of load module file 

(b) NOLIBRARY............... Specifies non-use of a library file 

(c) NOPRINT........cceeees Suppresses output of a list file 

(d) NOEXCLUDE............. Specifies linking of modules 

(e) NOAUTOPAGE........... Suppresses automatic paging 

(f)) NODEBUG.................. Suppresses output of debugging information 
(g) NOECHO.. .... Suppresses echo-back of a subcommand file 
(i) NOUDP sscscssssccsicccecces Suppresses display of undefined symbols 


Option Default: When an option is omitted, the following are the default choices. 


(a) OUTPUT (no parameters) 
(b) NOLIBRARY 

(c) NOPRINT 

(d) NOEXCLUDE 

(e) NOAUTOPAGE 

(f)) FORM=A 

(g) NODEBUG 

(h) ECHO 

(i) UDF 
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(3) 


(4) 


Abbreviating Option and Subcommand Names: Names of options and subcommands may 
be abbreviated to the point where the name can still be distinguished from other names. For 
example, consider the name “DEBUG.” 


Cannot be distinguished from DELETE or DEFINE, so an error occurs 
Cannot be distinguished from DELETE or DEFINE, so an error occurs 
-Recognized as DEBUG 

-Recognized as DEBUG 

-Recognized as DEBUG 

-No such name, so an error occurs 


Range of Validity of Options: When only a command line is specified, linkage is executed 
based only on the options specified. When subcommands are specified, options specified in 
the command line remain valid up to the first END subcommand specified (or up to the EXIT 


subcommand when no END is specified). However, if subcommands are specified which 
conflict with the function of an option, an error message is displayed, the option becomes 
invalid, and execution proceeds according to the subcommand specification. After the first 


END subcomman4d, all subsequent subcommand specifications are valid. 


EXAMPLE: 


%1nk A -NOOUTPUT 
:END 


. ‘ The OUTPUT subcommand is now valid. 
: OUTPUT GED : . 
: a eniasaiiiens so output file “loadfile.abs” is created. 


The NOOUTPUT option is in effect, 
so no output file is created. 
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In the following sections the format below is used to describe each option and subcommand. 


Heading for each option 
or subcommand 
No. INPUT 


Format Name Option Subcommand Negative Form 


Option or subcommand 
name, and format for 
specifying parameters; 
Paameers ===222~2~2~*é~“‘s~SSSTT underline indicates 
shortest abbreviation 


Function —<— Summary of option or 
subcommand functions 


Explanation —<— Detailed description 
of functions, and 
restrictions 


Examples ~<— Examples of option 
or subcommand 
specifications 


Note: The examples are written for UNIX system, write slash (/) instead of hyphen (-) for MS- 
DOS system, and write all options and subcommands in capital letters. 
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4.3 File Control 


4.3.1 INPUT - Specifies Input Files INPUT 
Format Name Option Subcommand Negative Form 
None INPUT None 


Function 


Explanation 


Examples 


Parameters <Input file name>[(<module name>[,<module name>...])] 
(,<Input file name> [(< module name>[,<module name>...])]...] 


Specifies files and modules to be input. 


(1) Outline of functions: 
* The files specified by parameters, or the specified modules in those files, are 
input to the Linkage Editor. 
* Three kinds of files can be specified object module files, load module files, and 
library files. 
* Modules may be specified only for library files, in which case only the specified 
modules from the library file will be input. 
° Ifthe file type is omitted from a file name, the Linkage Editor will automatically 
assume the type as follows. 
No module name specified............. “obj” 
Module name specified.................- “lib” 


(2) Restrictions in use: 

* Among load module files, only relocatable load modules may be specified. If an 
absolute load module is specified, an error will occur and the file will not be 
input. 

* Ifa module other than that in a library file is specified, an error will occur and 
the file will not be input. 

¢ The maximum number of input files that may be treated in one linkage process 
is 256, including library files. If more than 256 files are specified, an error will 
occur, and only the first 256 files specified will be input. To process more than 
256 files, use the multilinkage function. 

° Page type and non-page type modules may not be input at the same time. If both 
types of modules are input together, an error will occur and the Linkage Editor 
will stop execution. 


INPUTAmain 
Inputs the object module file “main.obj.” 


INPUTAfunclib (sin, cos),tan.o 
Inputs the modules “sin” and “cos” from library file “‘funclib.lib,” and 


inputs the object module file “tan.o.” 
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4.3.2 OUTPUT — Specifies an Output File OUTPUT 
Format Name Option Subcommand Negative Form 
OUTPUT OUTPUT NOOUTPUT 


Parameters [<Output file name>] 


Function Specifies a load module output file name. 


Explanation (1) Outline of functions: 
* Outputs the load module generated by the Linkage Editor to the specified file. 
* Ifthe file type is omitted from the file name, the Linkage Editor will 
automatically assign a file type according to the format of the load module file, 


as follows. 
Absolute format ..........:cccceseeceeeses “abs” 
Relocatable format... “rel” 


The format of the load module file is specified using the FORM option or 
subcommand. If no specification is made, absolute format is used. 

If no output file name is specified using the OUTPUT option or subcommand, 
the output file is given the name of the first specified input file plus the above 
file type. 

If the NOOUTPUT option or subcommand is specified, no load module file will 
be output. 


(2) Restrictions in use: 
* No parameters may be specified with the NOOUTPUT option or subcommand. 
¢ Ifan output file name is specified, it must be different from all input file names. 


Examples -OUTPUT=prgload 
Outputs load module file “prgload.abs” (or “‘prgload.rel”). 


-OUTPUT 
Outputs load module file with the name of the first specified object 
module file plus “abs” (or “.rel’’). 


OUTPUTAmain.10 
Outputs load module file “main.10.” 
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4.3.3 LIBRARY - Specifies Library Files LIBRARY 


Format 


Function 


Explanation 


Examples 


Name Option Subcommand Negative Form 


LIBRARY LIBRARY NOLIBRARY 


Parameters <Library file name>[,<library file name>...] 


Specifies input library files. 


(1) Outline of functions: 


Specifies library files which the Linkage Editor is to search if there are 
unresolved import symbols after linkage operations among specified input files 
are completed. 

If both user library files and system library files are specified, the Linkage Editor 
will search the user library files first. 

If no file type is specified with the library file name, the Linkage Editor 
automatically assumes this to be “lib.” 

If the NOLIBRARY option or subcommand is specified, there will be no input 
from a library file (including default libraries). When linkage is controlled by 
subcommand specification, however, the range of validity of this option is 
limited. For details see “Range of Validity of Options” under section 4.2. 


(2) Restrictions in use: 


Only library files created using the H Series Librarian may be input to the 
Linkage Editor. 

The maximum number of input files that may be treated in one linkage operation 
is 256, including library files. If more than 256 files are specified, an error will 
occur, and only the first 256 files specified will be input. To process more than 
256 files, use the multilinkage function. 

Page type and non-page type modules may not be input at the same time. If both 
types of modules are input together, an error will occur and the Linkage Editor 
will stop execution. 

No parameters may be specified with the NOLIBRARY option or subcommand. 


-LIBRARY=syslib. 


Specifies library file “syslib.” 


LIBRARYAsystem, debug 


Specifies library files “system.lib” and “debug.lib.” 
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4.3.4 PRINT - Specifies a List File PRINT 
tread ae 
Format Name Option Subcommand Negative Form 

PRINT PRINT NOPRINT 


Parameters Fa file — 
# 


Function Specifies a list file for output of linkage list. 


Explanation (1) Outline of functions: 

* Outputs a linkage list to the specified list file. 

+ Ifthe parameter “#” is specified, the list file is output to the standard output 
device. 
If no PRINT option or subcommand is specified, or if the NOPRINT option or 
subcommand is specified, the linkage list will not be output. 
If no file type is specified with the list file name, the Linkage Editor will 
automatically assume this to be “.map.” 
* On the contents of the linkage list, see section 6.1, “Linkage Lists.” 


(2) Restrictions in use: 
* No parameters may be specified with the NOPRINT option or subcommand. 


Examples -PRINT=linkage 
Outputs a linkage list to list file “linkage.map.” 


PRINTAearth.prn 
Outputs a linkage list to list file “earth.prn.” 
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4.3.5 EXCLUDE - Excludes Modules from Linking EXCLUDE 


Format 


Function 


Specifies that modules defining non-referenced import symbols should not be 


Explanation 


Examples 


linked. 


Name Option Subcommand Negative Form 


EXCLUDE EXCLUDE NOEXCLUDE 


Paramcters None 


linked. 


(1) Outline of functions: 


If an import symbol is not referenced, the module defining it is not linked. 

When the NOEXCLUDE option or subcommand is specified. podules defining 
non-referenced import symbols are linked. The defining modules are also linked 
if the EXCLUDE option or subcommand is omitted. 


(2) Restrictions in use: 


The EXCLUDE subcommand cannot be used after input files have been 
specified by the INPUT or EXCHANGE subcommand. 

The EXCLUDE option or subcommand can be specified only when the output 
load module is in absolute format. When the mulltilinkage function is used to 
create an absolute load module in the final linkage process, if the default library 
function is also used, the modules from the default library will be included in the 
first linkage process. If you want the default library to be included in the last 
linkage process, specify the NOLIBRARY subcommand for the intermediate 
linkage processes. 


~-EXCLUDE 


If an import symbol is not referenced, the module defining it is not 
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4.4 Memory Allocation 


Function 
Explanation 


4.4.1 START -— Specifies Start Address and Linkage Order of Sections START 
af i 
Format Name Option Subcommand Negative Form 

START START None 


Param- Option <Section name>[,<section name>...}[/[<page address>:]<start address>] 
eters UNIX: [,<section name>[,<section name>...][/[<page address>:]<start address>]...] 


MS- __ <Section name>[,<section name>... ][([<page address>:]<start address>)] 
DOS: _[,<section name>[,<section name>. ..]{([<page address>:]<start address>)]...] 


Sub- | I[<page address>:]<start address> 
com-  <Section name>[,<section name>...][ : 
mand ([<page address>:]<start address>) 


. [<page address>:]<start address> 
[,<section name>[,<section name>...][ | 


([<page address>:]<stan address>) | 


Specifies the order in which sections are linked, and their start addresses. 


@) Outline of functions: 
Sections are allocated from the specified address and in the specified order. 
+ If the start address is not specified and only the section linkage order is 
specified, and sections are assigned addresses starting from zero. 
+ Page address may be specified only for page type modules. If the page address 
is not specified, it is assumed to be zero. 
* The page address and start address are specified in hexadecimal notation. 
+ When sections not specified in the parameters are input, those sections are 
assigned after the series of sections with the highest specified start address. 
* Ifno START option or subcommand is specified, sections will be allocated to 
addresses starting from zero in the order of appearance. 
* The START option or subcommand can be specified more than once. 
(2) Restrictions in use: 
+ If the load module to be output is in relocatable format, the START option or 
subcommand may not be used. 
If a page address is specified for non-page type modules, an error will occur and 
the Linkage Editor will stop execution. 
* Hexadecimal numbers must start with numbers 0 through 9. 
EX: OABCD proper designation 
incorrect designation 
* Page addresses may be assigned in the range from 0 through OFF (hexadecimal). 
* The range of start addresses that may be specified varies with the H Series 
model. 
H8/500 Series: 0 through OFFFF (hexadecimal) 
H8/300 Series: 300HA* 0 through OFFFFFF (hexadecimal) 
Others 0 through OFFFF (hexadecimal) 
H32 Series: 0 through OFFFFFFFF (hexadecimal) 
SH Series: 0 through OFFFFFFFF (hexadecimal) 


Note: * “300HA” indicates the advanced mode of H8/300 Series. 
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Examples -START=CODE, DATA, BSS, STACK 
Sections are linked in the order “CODE,” “DATA,” “BSS,” “STACK,” 
and are allocated to addresses starting from zero. 


-START=CONTROL, BANKO, BANK1/0F00 
Sections are linked in the order “CONTROL,” “BANKO,” “BANK1,” 
and are allocated to addresses starting from OFO0 (hexadecimal). 


STARTARAMO, RAM1 (8000) , ROM1, ROM2 (1000) , ROMO 
Sections “RAMO” and “RAM1” are linked in that order and are allocated 
addresses starting from 8000 (hexadecimal). Sections “ROM1” and 
“ROM2” are linked in that order and are allocated to addresses starting 
from 1000 (hexadecimal). Section “ROMO” is allocated to addresses 
Starting from zero. 
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Function 


Explanation 


Examples 


4.4.2 ENTRY - Specifies Execution Start Address ENTRY 
Format Name Option Subcommand Negative Form 
ENTRY ENTRY None 


Parameters <Export symbol> 
Specifies the start address for executing a load module. 


(1) Outline of functions: 

* Sets the address value of an export symbol as the execution start address of a 
load module to be output. 

¢ Ifno ENTRY option or subcommand is specified and the output load module 
format is absolute, the execution start address becomes the start address of the 
first code section in the output load module. 


(2) Restrictions in use: 
* Ifan ENTRY option or subcommand is specified more than once, the last 
specified address is valid. 


-ENTRY=PRG_ENT 
The address of export symbol “PRG_ENT” is set as the execution start 
address. 


ENTRYAMAIN 
The address of export symbol ““MAIN” is set as the execution start 
address. 
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4.4.3 AUTOPAGE - Specifies Autopaging Function AUTOPAGE 
a a ee 
Format Name Option Subcommand Negative Form 


AUTOPAGE AUTOPAGE NOAUTOPAGE 
Parameters None 


Function Specifies autopaging in assignment of addresses to page type modules. 


Explanation (1) Outline of functions: 

+ When a page type module is linked, addresses are assigned by automatic paging. 

* Ifthe AUTOPAGE option or subcommand is not specified, or if the 
NOAUTOPAGE option or subcommand is specified, addresses are not assigned 
by automatic paging. 

(2) Restrictions in use: 

* The AUTOPAGE option or subcommand may not be specified when linking 
non-page type modules are linked. Such specification will result in an error, and 
the Linkage Editor will stop execution. 

* Ifthe NOAUTOPAGE option or subcommand is specified when page type 
modules are linked, sections may overlap page boundaries. If overlap occurs, 
the Linkage Editor displays a warning. 


LL 


Examples AUTOPAGE 
Addresses are assigned by autopaging. 


-NOAUTOPAGE 
Addresses are assigned without regard to page boundaries. 
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4.4.4 CPU — Specifies Address Check Using a CPU Information File CPU 
a cee 
Format Name Option Subcommand Negative Form 

CPU CPU None 


Parameters <CPU information file name> 


Function Specifies execution of an address check using a CPU information file. 


Explanation (1) Outline of functions: 

* The validity of addresses assigned to each section is checked, based on CPU 
information. In the following cases the section address assignment is regarded 
as invalid, and the Linkage Editor displays a warning. The sections, however, 
are output to the load module file without changing the addresses. 

(a) When sections are assigned addresses in areas other than memory. 
(b) When one section is assigned to addresses overlapping memory areas 
having different memory types and attributes. 

+ Ifno file type is specified with the CPU information file, the Linkage Editor will 
automatically assume this to be “.cpu.” 


(2) Restrictions in use: 
+ In the following cases the Linkage Editor displays a warning message, and the 
CPU option or subcommanid is invalid. 
(a) Relocatable format is specified as the load module output format with the 
FORM option or subcommand. 
(b) The information format of the CPU information file is invalid. 
(c) ACPU information file is specified for linkage processing of object 
modules not for the H8/300 or SH series. 
+ When a CPU option or subcommand is specified more than once, a warning 


message is displayed, and only the last-specified file is valid. 
enn enue SS Sa miele 
Examples -CPU=cinf 
Inputs CPU information file “cinf.cpu.” 


CPUAc300.inf 


Inputs CPU information file “c300.inf.” 
ss 
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4.4.5 ROM - 


Format 


Specifies Support of Storing Program in ROM ROM 
Name Option Subcommand Negative Form 
ROM ROM None 


Parameters UNIX: <Section 1>/<Section 2>[,<Section 1>/<Section 2>...] 
PC: (<Section 1>,<Section 2>)[(<Section 1>,<Section 2>),...] 
<Section 1>: section name of source initialized data area in ROM 
<Section 2>: section name of destination initialized data area in RAM 


Function 


Explanation 


Examples 


Reserves a RAM arca for updating initialized data values stored in ROM. 


(1) Outline of functions: 

¢ In the output load module, a section with the same scction size as the specified 
section | is reserved as section 2. Section 2 has the same section attributes as 
section 1. 

+ References to symbols declared in section 1 are relocated to addresses in 
section 2. Specify a relocatable section as section 1. 

* Up toten pairs of section is 1 and section 2 pairs can be specified. 

* For details of the support of storing program in ROM, see section 2.7, “Support 
of Storing Program in ROM.” 


(2) Restrictions in use: 

* The ROM option or subcommand cannot be specified when the output load 
module has the relocatable format. 

* If two sections have the same name and this name is specified as section 1, the 
section input first is selected. 

* An error occurs if section 1 does not exist. 

* A dummy section cannot be specified as section 1. 

* When an existing section is specified as section 2, the following conditions must 
be satisfied. 
(a) The size of section 2 in each unit is 0. 
(b) Section 2 is the relocatable section. 
(c) Both section 1 and section 2 have the same attribute. 

* The ROM option and subcommand are available in Linkage Editor Ver. 4 and 
later. 


UNIX: -ROM=D/RAM_SCT 
PC: /ROM= (D, RAM_SCT) 
Section RAM_SCT, equal in size to section D, is reserved in the output 
load module. References to symbols allocated to section D are relocated 
to addresses on RAM_SCT. 
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4.5 Execution Control 


4.5.1 EXCHANGE - Forcibly Replaces Units EXCHANGE 
Format Name Option Subcommand Negative Form 
None EXCHANGE None 


Parameters <Input file name>[(<unit name>[,<unit name>...})] 


Function Replaces units in an input file by units of the same name in the load module being 
processed by the Linkage Editor. 


Explanation (1) Outline of functions: 

* Units in the specified input file are replaced by units of the same name in the 
load module being processed by the Linkage Editor. 

* An object module file or load module file may be specified as the input file. 

* Ifaload module is specified as the input file without specifying unit names, all 
the units in that load module file will be usable for replacement. 

* Ifno file type is given with the input file name, the Linkage Editor will 
automatically assume “.obj” as the file type. 

* Replacement of units takes place after all input files have been included. If more 
than one EXCHANGE subcommand is specified, units will be replaced in the 
order of specification. 


(2) Restrictions in use: 

* An absolute load module may not be specified. If an absolute load module is 
specified, an error will occur, and the file will not be input. 

« A library file may not be specified as the input file. If a library file is specified, 
an error will occur, and the file will not be input. 


Examples EXCHANGEAdatain 
Replaces units in the object module file “datain.obj” by units of the same 
name in the load module file being processed. 


EXCHANGEAfunction. rel (tan, atan) 
Replaces the units “tan” and “atan” in relocatable load module file 
“function.rel” by units of the same name in the load module file being 
processed. 
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4.5.2 SUBCOMMAND - Specifies a Subcommand File SUBCOMMAND 
ee 
Format Name Option Subcommand Negative Form 


SUBCOMMAND SUBCOMMAND _ Nonc 


Parameters <Subcommand file name> 


Function Specifies a subcommand file for input. 


Explanation (1) Outline of functions: 


* Subcommands are input from the specified subcommand file. 

* Ifthe SUBCOMMAND option is not specified on the command line, and no 
input file is specified there, the Linkage Editor will link modules according to 
the subcommands input in interactive modc. 

+ Ifthe SUBCOMMAND option is not specified on the command line but one or 
more input files are specified there, the Linkage Editor will link modules 
according to the command line specification. 


(2) Restrictions in use: 

* When a subcommand file is specified on the command linc together with input 
files or other options, the subcommand file is executed as the last option, 
regardless of its specification position. For example: 


UNIX: lnk inl,in2 - SUB = linkage.sub - FORM = R 
@ e) 

Pc: LNK Inl,In2 / SUB = LINKAGE.SUB / FORM = R 
@ 6) 


This command line is interpreted and executed in the order @, ©, @. If 
FORM=A is specified in linkage.sub, FORM=A is valid (because it is 
interpreted afterward). 

* The SUBCOMMAND subcommand cannot be specified in a subcommand file. 


Example ~-SUBCOMMAND=1 inkage. sub 


Subcommand file “linkage.sub” is input, and the Linkage 
Editor links modules according to the contents of this file. 
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4.5.3 FORM - Specifies Output Load Module File Format FORM 
Format Name Option Subcommand _ Negative Form 
FORM FORM None 
Parameters A | 
R 
Function Specifies the output load module file format as either absolute or relocatable. 


Explanation (1) Outline of functions: 


+ If parameter “A” is specified, the load module file will be output in absolute 
format. 

* If parameter “R” is specified, the load module file will be output in relocatable 
format. 

¢ Ifno FORM option or subcommand is specified, the-load module will be output 
in absolute format. 


(2) Restrictions in use: 
* The parameter “R” cannot be specified when the ROM or START option or 
subcommand is specified. 


—FSFSSSFSFSSSSSSSSSeFFSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSeeeeeeeeSSSSe 
Examples 


-FORM=R 
The load module file is output in relocatable format. 


FORMAA 
The load module file is output in absolute format. 
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4.5.4 DEBUG - Specifies Output of Debugging Information DEBUG 
ar eam sei ic rr dh 
Format Name Option Subcommand Negative Form 

DEBUG DEBUG NODEBUG 


Parameters None 


Function Specifies incorporation of debugging information in the output load module file. 
ee 


Explanation (1) Outline of functions: 

* Incorporates debugging information in the output load module file. This 
information is required for symbolic debugging using the Simulator/Debugger. 

* Ifno DEBUG option or subcommand is specified, or if the NODEBUG option or 
subcommand is specified, debugging information will not be incorporated in the 
output load module file. 

(2) Restrictions in use: 


+ Ifthe NOOUTPUT option or subcommand is specified, specification of a 
DEBUG option or subcommand has no meaning. 


Examples DEBUG 
Debugging information is incorporated in the output load module file. 
-NODEBUG 
Debugging information is not incorporated in the output load module file. 
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4.5.5 END - Specifies End of Subcommand Input END 
Format Name Option Subcommand Negative Form 
None END None 


Parameters None 


Function Temporarily ends input of subcommands and begins linkage operation (after which 
subcommand input is resumed). 


Explanation (1) Outline of functions: 

* Temporarily ends input of subcommands and begins a linkage operation. After 
the linkage operation is completed, the Linkage Editor is initialized and 
subcommand input is resumed. 

¢ When the multilinkage function is used to perform multiple linkage operations 
with one execution of the Linkage Editor, the END subcommand indicates the 
end of one linkage process. 

¢ When the multilinkage function is not used, or when specifying the end of the 
final linkage process in a multilinkage operation, use the EXIT subcommand in 
place of the END subcommand. 


(2) Restrictions in use: 
+ If, for a single linkage process, the END subcommand is specified without 
specifying input files, an error will occur. 


Example END 
Temporarily ends subcommand input and begins a linkage operation. 
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4.5.6 EXIT — Specifies End of Linkage Operation EXIT 
Format Name Option Subcommand Negative Form 
None EXIT None 


Parameters None 


Function Ends subcommand input and begins linkage operation (subcommand input is not 
resumed). 


Explanation Outline of functions: 
¢ Ends subcommand input and begins linkage operation. After the linkage 
operation is completed, ends the Linkage Editor execution. 
* When execution is controlled from a subcommand file, if no EXIT subcommand 
is specified, the Linkage Editor waits for further subcommand input. 
* If, for a single linkage process, the EXIT subcommand is specified without 
specifying input files, an error will occur. 


Example EXIT 
Ends subcommand input and begins linkage operation. 
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4.5.7 ABORT — Specifies Forced End of Linkage Operation ABORT 
Format Name Option Subcommand Negative Form 
None ABORT None 


Parameters None 


Function Specifies forced end of linkage operation. 


Explanation Outline of functions: 
¢ Forcibly ends Linkage Editor operation. 
* The ABORT subcommnad is useful to interrupt Linkage Editor operation when a 
mistake such as subcommand input mistake has been made. 


Example ABORT 
Brings Linkage Editor execution to a forced end. 
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4.5.8 ECHO - Specifies Subcommand File Echo-Back ECHO 
Format Name Option Subcommand Negative Form 
ECHO ECHO NOECHO 


Parameters None 


Can select whether or not to suppress echo-back of subcommands when a 


* The ECHO option or subcommand displays subcommands on the console when 
a subcommand file is executed. Subcommands are displayed even if the ECHO 
option or subcommand is not specified. 

* The NOECHO option or subcommand suppresses display of subcommands on 
the console when a subcommand file is executed. 


Function 

subcommand file is executed. 
Explanation Outline of functions: 
Examples ECHO 


Subcommands exccuted will be displayed on the console when a 
subcommand file is executed. 
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4.5.9 UDF — Specifies Display of Undefined Symbols UDF 
Format Name Option Subcommand Negative Form 
UDF UDF NOUDF 


Parameters None 


Function Specifies whether to display a warning message when an undefined symbol remains. 


Explanation (1) Outline of functions: 

+ Warming message 105 is displayed if an undefined symbol remains when a 
relocatable load module is created. This message is also displayed if an 
undefined symbol remains when the UDF option or subcommand is omitted. 

+ When the NOUDF option or subcommand is specified, a warning message is not 
displayed if there is an undefined symbol when a relocatable load module is 
creatcd. 


(2) Restrictions in use: 
* The NOUDF option or subcommand is ignored when an absolute load module is 
created. 


Examples —-FORM=R-NOUDF 


A warning message will not be displayed if there is an undefined symbol 
when the relocatable load module is created. 
=) SSSSSSSSSSSSSSSSSS—————— 
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4.6 Debugging Support 


4.6.1 LIST — Displays Interim Linkage Information LIST 
Format Name Option Subcommand Negative Form 
None LIST None 
Parameters M 
U 
xX 
Function Displays linkage information of an input file. 


Explanation (1) Outline of functions: 
* Outputs linkage information to the standard output device concerning the files 
currently being input. 
* Content of the displayed information depends on the specified parameters, as 
follows. 
M........Displays a link map 
U.........Displays unresolved import symbols 
Ricasines Displays export symbols 


(2) Restrictions in use: 

* To display linkage information according to the input files, the information 
displayed is restricted as follows. 

* When parameter M is specified 
The start address of a relocatable section is always 0. 

¢ When parameter U is specified 
The display shows import symbols for which there is no corresponding export 
symbol in the input files specified in INPUT subcommands up to the location of 
the LIST subcommand. 


Examples LISTAM 


Displays a linkage map for the load module being processed. 


LISTAU 
Displays unresolved import symbols in the load module being processed. 
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4.6.2 RENAME - Changes the Names of Units, Export 


Symbols, or Import Symbols RENAME 
Format Name Option Subcommand Negative Form 
None RENAME None 
Parameters UN=<unit name 1> (<unit name 2>) 


ER=<unit name>.<import symbol 1> 
(<import symbol 2>) 


ED=<unit name>.<export symbol 1> 
(<export symbol 2>) 


UN=<unit name 1>(<unit name 2>) 


ER=<unit name>.<import symbol 1> 
(<import symbol 2>) 


ED=<unit name>.<export symbol 1> 
(<export symbol 2>) 


Function Changes the names of units, export symbols or import symbols in input files. 


Explanation (1) Outline of functions: 

* Changes the names of each specified unit, export symbol, or import symbol in 

input files to the name designated in parentheses (‘‘( )”). 

+ In the case of a unit, the unit name specified following “UN=” is changed to the 
unit name in parentheses. 
In the case of an import symbol, the symbol name specified following “ER=” is 
changed to the name in parentheses. The import symbol name is preceded by the 
name of the unit in which the symbol exists, and is set off from the unit name by 
a period (.). 
In the case of an export symbol, the symbol name specified following “ED=” is 
changed to the name in parentheses. The export symbol name is preceded by the 
name of the unit in which the symbol exists, and is set off from the unit name by 
a period (.). 
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Explanation (2) Restrictions in use: 


¢ The RENAME subcommand will affect the input files specified only in the first 
INPUT subcommand after the RENAME subcommand. 
* Only the following five subcommands may be specified immediately after the 
RENAME subcommand: 
(a) INPUT subcommand 
(b) EXCHANGE subcommand 
(c) RENAME subcommand 
(d) DELETE subcommand 
(e) ABORT subcommand 
When more than one RENAME subcommands are specified, or when RENAME 
and DELETE subcommands are specified together, operation takes place in the 
order of specification. 


Examples RENAMEAUN=datalist (datalst1) 
Unit “datalist” is renamed as “‘datalst1.” 


RENAMEAED=cnt 1 . TRUNK (P_TRUNK) , ER=cnt11.REC_DATA (RECV_DATA) 
Export symbol “TRUNK” in unit “cnu” is changed to “P_TRUNK.” 
Likewise, import symbol “REC_DATA” in unit “cntll” is changed to 


“RECV_DATA.” 
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4.63 DELETE - Deletes Units or Export Symbols DELETE 
Format Name Option Subcommand Negative Form 
None DELETE None 
Parameters | UN=<unit name> 
ED=<unit name >.<export symbol name> 


UN=<unit name> 
* | ED=<unit name>.<export symbol name> |” 


Function Specifies deletion of units or export symbols from input files. 


Explanation (1) Outline of functions: 
+ Deletes the specified units or export symbols from input files. 
+ In the case of a unit, the unit specified following “UN=” is deleted. 
+ In the case of an export symbol, the symbol specified following “ED=” is 
deleted. The export symbol name is set off by a period (.) from the name of the 
unit in which it exists. 


(2) Restrictions in use: 

* The DELETE subcommand will not affect input files already specified. This 
subcommand must be specified prior to specification of the input files in which 
the name of the unit or externally defined symbol to be deleted is found. 

* The following five subcommands may be specificd immediately after the 
DELETE subcommand: 

(a) INPUT subcommand 

(b) EXCHANGE subcommand 
(c) DELETE subcommand 

(d) RENAME subcommand 
(e) ABORT subcommand 

* When RENAME and DELETE subcommands are specified together, operation 
takes place in the order of specification. 


Examples DELETEAUN=snap_unit 
Deletes unit “snap_unit.” 


DELETEAUN=dummy , ED=main.DUMMY_ENTER 
Deletes unit “dummy.” Also, deletes export symbol “DUMMY_ENTER” 
in unit “main.” 
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4.6.4 DEFINE - Forcibly Defines an Import Symbol DEFINE 
Format Name Option Subcommand Negative Form 
DEFINE DEFINE None 


Param- Option 
eter UNIX: <Import symbol name>/ 


<numeric value> ) 
[<page address>:]<address> 
<export symbol name> 


{,<import symbol name>/4 [<page address>:]<address>}...] 


{ <numeric value> 
<export symbol name> 


MS- <numeric value> 

DOS: <import symbol name>( { [<page address>:]<address>}) 
<export symbol name> 
<numeric value> 

[,<import symbol name>(4 [<page address>:]<address>>)...] 

<export symbol name> J 

Sub- /) (<numeric value> 

com- <Import symbol name> [<page address>:]<address> 

mand (J |<export symbol name> ) 


/) {<numeric value> 
[,<import symbol name> [<page address>:]<address> rt | 
) 


(} (<export symbol] name> 


Note: Specify a right parenthesis “*)” only if the preceding numeric value, 
address, or externally defined symbol name is delimited by a left 
parenthesis “(.” 

Function Specifies forced definition of import symbols. 


Explanation (1) Outline of functions: 
* Forcibly defines each specified import symbol with the specified numeric value, 
address or export symbol value. : 
* ¢ Page address can be specified only for page type modules. If the page address is 
not specified, zero is assumed. 


* Numeric values, page addresses, and addresses are specified in hexadecimal 
notation. 
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Explanation 


Examples 


(2) Restrictions in use: 
* When the assigned value is that of an export symbol, it must be one that has 
already been defined. 
+ Ifa page address is specified for non-page type modules, an error will occur and 
the Linkage Editor will stop execution. 
+ Hexadecimal numbers must start with the numbers 0 through 9. 
° The range of page addresses is 0 through OFF (hexadecimal). 
+ The range of addresses that may be specified varies with the H Series model. 
H8/S00 Series: 0 through OFFFF (hexadecimal) 
H8/300 Series: 300HA* 0 through OFFFFFF (hexadecimal) 
Others 0 through OFFFF (hexadecimal) 
H32 Series: 0 through OFFFFFFFF (hexadecimal) 
SH Series: 0 through OFFFFFFFF (hexadecimal) 


Note: * “300HA” indicates the advanced mode of H8/300 Series. 


* Values defined by the DEFINE subcommand cannot be used in relocatable load 
modules. 

* When the EXCLUDE option or subcommand is specified, non-referenced import 
symbols specified by the DEFINE subcommand are ignored. 


-DEFINE=PORT10/0E8 
Defines undefined import symbol “PORT10” as a symbol having the 
value OE8 (hexadecimal). 


DEF INEAMAIN_RTN(PRG_EXIT) 
Defines undefined import symbol “MAIN_RTN” as having the same 
value as export symbol “PRG_EXIT.” 
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Section 5 Input to the Linkage Editor 


5.1 Object Module Files 


The Linkage Editor can accept as input the object module files output by the H Series C Compiler 
or Assembler. 


5.2 Relocatable Load Module Files 


Relocatable load module files output by this Linkage Editor may be re-input. Absolute load 
module files may not be re-input. 


5.3 Library Files 


Library files created using the H Serics Librarian may be input to the Linkage Editor. Modules in 
library files may be specified individually, or the LIBRARY option or subcommand may be used 
to input modules contained in library files automatically. Scc further under section 4.3.3, 
“LIBRARY -— Specifies Library Filcs.” 


5.4 Default Library Files 


A library file created by the H Scries Librarian can be input implicitly without specifying the 
LIBRARY option or subcommand. This is called the default library function. 


A default library is input when the following three conditions are satisfied: 


+ A logical name reserved as a default library name is assigncd to the library file before the 
library files is input to the Linkage Editor. 


* The NOLIBRARY option or subcommand is not specified. 


+ An unresolved import symbol remains after the librarics specified by the LIBRARY option or 
subcommand have been searched. 


The Linkage Editor inputs the library files assigned to the following logical names in the order 1, 
2, 3,.and searches for modules that define unresolved import symbols. 


i. HLNK_LIBRARY1 
2. HLNK_LIBRARY2 


3. HLNK_LIBRARY3 
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The user can specify library files corresponding to these logical names by using the setenv 
command for UNIX system and the SET command for PC system of the operating system of the 
operating system. 


EXAMPLE: 


UNIX system: 

% setenv HLNK LIBRARY] user.lib 
PC system: 

> SET HLNK_LIBRARY1=USER.LIB 


User library user.lib is assigned to the logical name HLNK_LIBRARY1. 
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Section 6 Output from the Linkage Editor 


6.1 Linkage Lists 


When the PRINT option or subcommand or the LIST subcommand is specified, the contents of a 
load module file being processed are output to the standard output device or to a file, as follows. 


(1) Input information (PRINT only) 
(2) Link map list (PRINT or LIST M) 
(3) Export symbol list (PRINT or LIST X) 
(4) Unresolved import list {PRINT or LIST U) 
(5) RENAME/DELETE list (PRINT only) 
(6) DEFINE list (PRINT only) 


The formats in which these lists are output are shown below. 
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(1) Input Information: Information input as command line parameters, interactive mode 
subcommands, or subcommand files is output in the format shown in figure 6-1. 


H SERIES LINKAGE EDITOR Ver. 5.0B 
LINK COMMAND LINE 
LNK -sub=func.sub 


® 


LINK SUBCOMMANDS 


inp main 

rename ed=sin.sin0(sin1l) 

delete ed=sin.sin3 

inp sin 

define undefl (100) , undef2 (sin1) 


print fmap 

inp cos 

inp tan 

inp calc.lib(division) 
forma 

out func 

rom (SECT1, SECI1N) 

exit 

** sinO IS RENAMED TO sinl 
** sin3 IS DELETED 

** 105 UNDEFINED EXTERNAL SYMBOL (division.undef3) 


Figure 6-1 Typical Output of Input Information 
@® Shows the character string input on the command line. 
@ Shows the character strings input as subcommands in interactive mode, or input from a 


subcommand file. Also shows error messages or informative messages in response to this 
input. 


76 


HITACHI 


(2) Link Map List: 


(a) When the PRINT option or subcommand is specified, information on each section is 
output in the format shown in figure 6-2. 


H SERIES LINKAGE EDITOR Ver. 5.0B 
LINKAGE EDITOR LINK MAP LIST sae 


SECTION NAME START - END LENGTH 
UNIT NAME 


ATTRIBUTE : CODE NOSHR ROM 


@ ® © 
SECT1 H'00000000 - H'00000004 —_-#'':00000005 


® © main © main 


@ 
H'00000006 - H'00000017 H'00000012 

sin 
H'00000018 - H'00000019 H'00000002 

cos 
H'0000001la - H'0000002d H'00000014 

tan tan 
H'0000002e - H'00000043 H'00000016 

division division 


* TOTAL ADDRESS * H'00000000 H' 00000043 H'00000044 


@® ® 


Figure 6-2 Typical Link Map List Output Using PRINT 
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(b) When parameter “M” is specified in the LIST subcommand, information on each file is 
output in the format shown in figure 6-3. 


H SERIES LINKAGE EDITOR Ver. 5.0B 


me LINKAGE EDITOR LINK MAP LIST ERE 


CODE NOSHR 
H' 00000000 ~ H'00000004 H'00000005 
® ® 


Figure 6-3 Typical Link Map List Output Using LIST 
@® Shows section names in the order in which sections are linked. 


@ Shows the attribute as follows. 
DATA: data or common section 
CODE: code section 
DUMMY: dummy section 
STACK: stack section 
RESV: reserved 
UNDEF: undefined 
i badlaalaaiaata unused 


@® Shows the following link attributes. 
SHR: common link 
NOSHR: simple link 
DUMMY: dummy link 
UNDEF: link attribute undefined 
RAK. unused 


® Displayed for a section related to the support of storing program in ROM. 


ROM_ ROM section (section 1 in the ROM option or subcommand) 
RAM_ RAM section (section 2 in the ROM option or subcommand) 
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© Shows start address and end address of the object in hexadecimal notation. In the case of 
page type modules, the page address and address are separated by a colon (:) as follows. 


H’XxXxX 2 XXXX 


address 
page address 


Shows size of object in hexadecimal notation. 


Shows unit name. 


® 8 ® 


Shows module name. 


© 


Shows start address and end address of the section. 
In the case of page type modules, the page address and address are separated by a colon (:) as 
follows. 


H'xXxxx ! XXXX 


address 
page address 


@ Shows total size of the section. 


@ Shows the file name (LIST only). 
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(3) Export Symbols List: This list is output when there are export symbols. 


(a) When the PRINT option or subcommand is specified, a list is output in the format shown 
in figure 6-4. 


H SERIES LINKAGE EDITOR Ver. 5.0B 


RRS LINKAGE EDITOR EXTERNALLY DEFINED SYMBOLS LIST 


SYMBOL NAME ADDR 


cosl H'0000000a 
sinl H'00000000 
sin2 H'00000011 


® 12) 


Figure 6-4 Typical Export Symbol List Output Using PRINT 


(b) When paramenter “X” is specified by the LIST subcomman4d, a list is output as shown in 
figure 6-5. 


H SERIES LINKAGE EDITOR Ver. 5.0B 
baie LINKAGE EDITOR EXTERNALLY DEFINED SYMBOLS LIST 


SYMBOL NAME ADDR 


cosl H'0000000a 


sinl H'00000000 
sin2 H'00000011 
® @ 


Figure 6-5 Typical Export Symbol List Output Using LIST 
@® Shows export symbols in alphabetical order. 


@ Shows the value of each export symbol in hexadecimal notation. In the case of page type 
modules, the page address and address are separated by a colon (:) as follows. 


H'xxxx : XXxXx 


address 
page address 
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@® Shows the type of symbol as follows. 
DAT: data/variable name 
EQU: symbol name defined as constant value 
ENT: entry name 
***: undefined/unuscd 


(4) Unresolved Import Symbol List: This list is output only when there are undefined symbols 
remain. 


(a) When the PRINT option or subcommand is specified, a list is output in the format shown 
in figure 6-6. 
H SERIES LINKAGE EDITOR Ver. 5.0B PAGE: 
LINKAGE EDITOR UNRESOLVED EXTERNAL REFERENCE LIST 


FILE NAME : cale.lib 


® 


MODULE NAME : division 


) 
UNIT NAME : division 


@ 


SYMBOL NAME 
undef3 


@ 


Figure 6-6 Typical Unresolved Import Symbol List Output Using PRINT 


(b) When parameter “U” is specified by the LIST command, a list is output as shown in 
figure 6-7. 
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© © ® 8 Oo 


H SERIES LINKAGE EDITOR Ver. 5.0B PAGE: 
ae LINKAGE EDITOR UNRESOLVED EXTERNAL REFERENCE LIST wae 
FILE NAME : cale.lib 
® 
MODULE NAME : division 
@ 
UNIT NAME : division 
©) 
SYMBOL NAME TYPE 
undef1 wR 
undef2 RK 
undef3 pabaal 


® 


Figure 6-7 Typical Unresolved Import Symbol List Output Using LIST 


Shows name of file containing undefined symbol. 
Shows name of module containing undefined symbol. 
Shows name of unit containing undefined symbol. 
Shows undefined symbol names in alphabetical order. 


Shows undefined symbol attributes as follows. 
DAT: data/variable name 

ENT: entry name 

***: undefined/unused 
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(5) RENAME/DELETE List: When RENAME or DELETE subcommands are used to change 
the name of units or symbols or delete units or symbols, specification of the PRINT option or 
subcommand results in output of a list in the format shown in figure 6-8. 

H SERIES LINKAGE EDITOR Ver. 5.0B PAGE: 1 


liad LINKAGE EDITOR RENAME/DELETE LIST ball 


FILE NAME : sin.ob}j 
O) 


UNIT NAME : sin 


RENAME /DELETE 
RENAME 
DELETE 


© 


Figure 6-8 Typical RENAME/DELFTE List 


(2) 


Shows names of files containing the unit or symbol to be renamed or deleted in the order 
input. 


Shows the unit name. If the unit was renamed or deleted, the old unit name is shown. 
Shows the name before changed. 


Shows the name after changed. No name is shown in case of a DELETE. 


© © © ® 


Shows the type specified by subcommand, as follows. 
UN: unit name 

ED: export symbol 

ER: import symbol 


© Shows whether the subcommand was a RENAME or a DELETE. 
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(6) DEFINE List: When an import symbol is forcibly defined using the DEFINE option or 
subcomman4d, specification of the PRINT option or subcommand results in output of a list in 
the format shown in figure 6-9. 
H SERIES LINKAGE EDITOR Ver. 5.0B 


ane LINKAGE EDITOR DEFINE LIST ee 


UNDEFINED SYMBOL DEFINED SYMBOL DEFINED VALUE 


undef1 H'00000100 


undef2 i H' 00000000 
® @ 


Figure 6-9 Typical DEFINE List 


® Shows forcibly defined symbol name. 
@ Shows the name of the export symbol which is specified. 


@® Shows the value of the defined symbol in hexadecimal notation. In the case of page type 
modules, the page address and address are separated by a colon (:) as follows. 
H'Xxxx : XXXxX 


address 
page address 


6.2 Load Module File 


The Linkage Editor links a number of object modules or relocatable load module files and outputs 
them as a single load module file. Depending on the specification made with the FORM option or 
subcommand, the load module file is output in either absolute or relocatable format. A detailed 
explanation of the FORM option and subcommand is given in section 4.5.3, “FORM — Specifies 
Output Load Module File Format.” 
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6.3 Console Messages 
The Linkage Editor shows the following messages on the standard output device. 
(1) Opening Message: This is displayed when Linkage Editor command name “LNK” is input. 


H SERIES LINKAGE EDITOR Ver. 5.0B 


Copyright (C) Hitachi, Ltd. 1989 


Licensed Material of Hitachi, Ltd. 


(2) Normal Completion Message: This is displayed when the load module file editing has been 
completed normally. 


LINKAGE EDITOR COMPLETED 


(3) Abort Message: This is displayed when the load module file editing is ended before 
completion, due either to an error or to specification of an ABORT subcommand. 


LINKAGE EDITOR ABORT 


(4) Subcommand Request Prompt: In intcractive mode, a colon (:) indicates that the Linkage 
Editor is waiting for subcommand input. 


[| 


(5) Subcommand Continuation Prompt: When continuation of a subcommand is specified 
during interactive mode execution, a hyphen (-) indicates that the Linkage Editor is waiting 
for continuation of the input. 


aia 
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(6) Informative Message: Informative messages indicate the result of Linkage Editor 


processing, for example when units are replaced or when an export symbol is renamed. The 
messages are output in the following format. 


** A <information> 


1st column 


A list of informative messages is given in table 6-1. 


Table 6-1 List of Informative Messages 


No. (Informative message) 


(Meaning of message) 


1 


4 


5 


6 


<Unit name 1> IS REPLACED WITH <unit name 2>(<file name>) 

<Unit name 1> has been replaced by <unit name 2> from <file name>. 
<External name 1> IS RENAMED TO <external name 2> 

Name of <external name 1> has been changed to that of <external name 2>. 
<External name> IS DELETED 

<External name> has been deleted. 

DUPLICATE UNIT-(<unit name>) IN (<file name>) IS DELETED 


More than one units of the same name <unit name> have been found, and the unit of that 
name in <file name> has been deleted. 


<External name> CANNOT DEFINED 

<External name> could not be found, and therefore could not be forcibly: defined. 
<External name>/<unit name> CANNOT RENAMED 

<External name> or <unit name> could not be found, and therefore could not be renamed. 
<Externally defined name>/<unit name> CANNOT DELETED 


<Externally defined name> or <unit name> could not be found, and therefore could not be 
deleted. 


<Unit name> CANNOT REPLACED 


<Unit name> could not be found, and therefore could not be replaced. 
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Section 7 Error Messages 


When options or subcommands are specified incorrectly, or if an error is detected during the 
linkage process, an error message is output. The Linkage Editor outputs error messages in the 
following form. 


**A <Error number>A<error message>[(<additional information>) ] 


lst column 


Error Number: The first digit indicates the level of the error (xx represent the second and third 
digits). 


1xx: Waring Processing of the particular module is skipped. 

2xx: Error In the case of input from the command line or a subcommand file, 
processing is stopped. In interactive mode, processing of the 
subcommand is stopped when the error is detected, and the next 
subcommand is requested. 

3xx: Fatal error Processing is stopped. 


A list of errors is given below in tables 7-1, 7-2, and 7-3 in the following format. 


ErrorNumber Error Message Additional Information 


Nature of Error 


Linkage Editor actions and corrective actions 


Notation used in table: —: No additional information 
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Table 7-1 List of Warning Messages 


101 DUPLICATE OPTION/SUBCOMAND Option/subcommand name 


The same option or subcommand was specified more than once. 


Only the last-specified option or subcommand is valid. 
102 TOO LONG IDENTIFIER UP TO 32 Name 


Name of a unit, section, or symbol over 32 characters was specified. 


Name is valid up to 32nd character. The rest is ignored. 
104 DUPLICATE SYMBOL Symbol name 


The same export symbol is defined more than once. 


Only the first appearing symbol is valid. 
105 UNDEFINED EXTERNAL SYMBOL Unit name, Symbol name 
An undefined symbol was imported. 


The import is invalid, and zero is assumed as the value. 

106 REDEFINED SYMBOL Symbol! name 
A previously defined symbol was defined using the DEFINE subcommand or option. 
The DEFINE specification is invalid. 

107. SECTION ATTRIBUTE MISMATCH Section name 


Two sections with the same name but different attributes or boundary alignment were input. 


The sections are processed as separate sections. 
108* RELOCATION SIZE OVERFLOW Unit name, Section name — offset value 


Relocation result exceeds the relocation size. 


Result is rounded off to fit the relocation size. 
109 ENTRY POINT MULTIPLY DEFINED — 


Execution start addresses were specified in more than one object modules. 


The first appearing execution start address is valid. 

110 SECTION ADDRESS EXCEED PAGE BOUNDARY Section name 
A section overlaps a page boundary. 
Specify AUTOPAGE option or subcommand. 

111. DUPLICATE SECTION NAME Section name 


Same section name was specified in options or subcommands. 


The first section is valid. 
112 ILLEGAL CPU INFORMATION FILE FORMAT _ 


The file format of the CPU information file is not correct. 


The CPU option or subcommand specification is invalid. 
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Table 7-1 List of Warning Messages (cont) 


113 


114 


115 


116 


117 


118 


119 


CONFLICTING DEVICE TYPE _ 


The specified CPU information file is for a different CPU from that for which the input object 
module is intended. 


The CPU information file specification is invalid. 


SECTION IS NOT IN SAME MEMORY AREA Section name: xxxx-yyyy 


A section overlaps different memory areas. Addresses xxxx to yyyy are not allocated to one 
memory area. : 


The section is output to the load module without change. 

INACCESSIBLE ADDRESS RANGE Section name 

A section was assigned to a memory area that cannot be used. 

The section is output to the load module without change. 

INVALID CPU OPTION/SUBCOMMAND _ 

The CPU option or subcommand was specified for a relocatable load module file. 
The CPU option or subcommand specification is invalid. 


ADDRESS SPACE DUPLICATE _ 

Sections overlap. 

The load module is output as is. 

INVALID UDF OPTION/SUBCOMMAND _— 

The NOUDF option or subcommand was specified for an absolute output load module. 
The NOUDF option or subcommand is invalid. 
RELOCATION VALUE IS ODD 

Relocation value for the displacement is odd. 

The LSB is rounded down to fit to the relocation size. 


Unit name, section name — offset value 


Note: * Warming message 108 is output if a data size designated at assembly or compile is 
exceeded as a result of address resolution by the Linkage Editor. 


Example: 


Assembler source program (example.src) 


.section secl, code In this example the value assigned 
label .equ $ to the label during linking is 1000, 
. : which exceeds the 1-byte data size, 
i and therefore warning message 108 
Janba.d dabei ¢ i byte data | 1S output. The upper byte (10) of 
: 1000 is disregarded, leaving 0 
(zero) as the data value. 


Assembly and linkage commands 


asm8 example 
ink example-start=secl1/1000 
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Table 7-2 List of Error Messages 


201 ILLEGAL SUBCOMMAND/OPTION _ 
An illegal subcommand (or option) was specified. 


Specify a valid subcommand (or option). 
202 SYNTAX ERROR — 
Syntax of the specified subcommand (or option) is incorrect. 


Check the syntax and re-specify the subcommand (or option). 
203 TOO LONG SUBCOMMAND LINE _ 
Length of the subcommand entry exceeds 255 characters. 


Re-specify, keeping the length within 255 characters. 
204 ILLEGAL SUBCOMMAND SEQUENCE _ 
Order of subcommand specification is invalid. 


Check the order of subcommand specification and re-specify. 
207 ILLEGAL SECTION NAME Section name 
The specified section name is invalid. 


Specify a proper section name. 
208 ILLEGAL SYMBOL NAME Symbol name 
The specified symbol name is invalid. 


Specify a proper symbol name. 
210 TOO MANY INPUT FILES _ 
Attempt was made to input more than 256 input files at one time. 


Create a relocatable load module file, then specify the remaining input files by re-inputting 
the load module file. 


211. CANNOT FOUND FILE File name 
The specified file cannot be found. 


Check the specified file name, then re-specify. 
212 CANNOT FOUND UNIT Unit name 


The specified unit cannot be found. 


Check the specified unit name, then re-specify. 

213 CANNOT FOUND MODULE Module name 
The specified module cannot be found. 
Check the specified module name, then re-specify. 

214 DUPLICATE START ADDRESS SPECIFIED _— 


The same start address was specified more than once. 


Change the start address, then re-input. 
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Table 7-2 List of Error Messages (cont) 


216 


217 


219 


PAGE ADDRESS EXCEEDED _ 
A page address exceeds the permitted range. 


Check the page address and re-specify. 

SUBCOMMAND COMMAND IN SUBCOMMAND FILE — 

The SUBCOMMAND subcommand appeared in a subcommand file. 
Remove the SUBCOMMAND subcommand from the subcommand file. 
INVALID ADDRESS address 

The specified address exceeds the permitted range. 


The specified address exceeds the address range of the specified device. Check the value 
of the specified address, then re-execute. 


220 


TOO MANY ROM COMMANDS — 


More than 10 pairs of section names were specified in a ROM subcommand. 


Specify 10 pairs or less. 


—————— eee 


Table 7-3 List of Fatal Error Messages 


Check the specified file name. If the file name is correct, the disk may be full, or there may 


Check the specified file name. If the file name is correct, the disk may be full, or there may 


Check the specified file name. If the file name is correct, the disk may be full, or there may 


301 ILLEGAL COMMAND PARAMETER — 
An improper command parameter was specified. 
Check the command parameters and re-execute. 
302 CANNOT OPEN FILE File name 
The file cannot be opened. 
be a disk hardware problem. After checking the problem, re-execute. 
303 CANNOT READ INPUT FILE File name 
The file cannot be input. 
be a disk hardware problem. After checking the problem, re-execute. 
304 CANNOT WRITE OUTPUT FILE File name 
The file cannot be output. 
be a disk hardware problem. After checking the problem, re-execute. 
305 CANNOT CLOSE FILE File name 


The file cannot be closed. 


Check the specified file name. If the file name is correct, the disk may be full, or there may 
be a disk hardware problem. After checking the problem, re-execute. 
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Table 7-3 List of Fatal Error Messages (cont) 


306 ILLEGAL FILE FORMAT File name 


The specified file format is incorrect. 


Check the file contents and specified file name, then re-execute. This message is output 
when the object file format is illegal, for example because there are two or more import 
symbols with the same name in the same unit, or two external symbol names were made 
identical by the RENAME subcommand. 


307 ILLEGAL RECORD FORMAT File name 


There is an illegal record in the specified file, or division by zero occurred. 
Check the source program contents. Re-assemble or re-compile, then re-execute. 
308 SECTION ADDRESS OVERFLOW Section name of the specified device 


The address allocated to a section exceeds the allowable range. 


The address allocated to the section exceeds the address range of the specified device. 


Change the section start address or rearrange the user program, then re-execute. 


309 ADDRESS OVERFLOW = 
The specified address exceeds the address range allowed for the particular CPU. 
Check the specified address, then re-execute. 

310 MEMORY OVERFLOW _ 


There is no space remaining in the Linkage Editor’s usable memory. 


Expand the memory or alter the user program, then re-execute. 
311. PROGRAM ERROR nnn 


There is an error in the Linkage Editor program. 


The Linkage Editor is inoperable. Check the program error number (nnn), then contact your 


Hitachi representative. 
312 ILLEGAL START ADDRESS ALIGNMENT Address 


The specified address conflicts with the boundary alignment number of the object module. 


Check the boundary alignment number of the object module, then re-execute. 
314. CANNOT FOUND SECTION Section name 


The specified section name cannot be found. 


Check the section name, then re-specify. 
319 AUTOPAGE SPECIFIED AT NON-PAGE TYPE — 
The AUTOPAGE option/subcommand was specified when non-page type files were input. 


Check the input file contents, then re-specify. 
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Table 7-3 List of Fatal Error Messages (cont) 


321 


322 


323 


325 


326 


327 


328 


PAGE ADDRESS OVERFLOW _— 


The page address overflows the allowable range 


Change the section start address or the user program so that the page address will be within 
the allowable range of 0 - OFF (hexadecimal), then re-execute. 


PAGE ADDRESS SPECIFIED AT NON-PAGE TYPE _ 


For a non-page type input file, a page address was specified with the START or DEFINE 
option/subcommand. 


Check the specified file name and option or subcommand content, then re-execute. 


SECTION SPECIFIED AT ROM OPTION Section name 
/SUBCOMMAND DOES NOT EXIST 


A section specified in a ROM command does not exist. 

Check the section name, and specify again. 

ILLEGAL START SECTION Section name 
A section specified by a START command has an illegal attribute. 

Check the section attributes, and re-specify. 

CANNOT READ _ 

Input failed from a file (including the standard input device). 


Check the specified file name. If the file name is correct, the disk may be full, or there may 
be a disk hardware problem. After checking the problem, re-execute. 


SYMBOL ADDRESS OVERFLOW Symbol! name 

The address assigned to a symbol exceeded the permitted range for the specified device. 
Change the section start address or rearrange the user program, then re-execute. 
ILLEGAL ROM SECTION Section name 

Section 2 specified in a ROM subcommand or option is invalid. 


a ee 
The size of section 2 is not 0, section 2 is the absolute section or the attribute of section 2 is 


different from that of section 1. Check the size and attribute of section 2, and re-specify. 
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Section 8 Restrictions 


Restrictions on the Linkage Editor are shown in table 8-1. If the numerical restrictions are 
exceeded, linkage operations cannot be performed. 


Table 8-1 Restrictions on Linkage Editor Processing 


No. Item Restrictions Remarks 
1. Number of input files Max 256 
2 Input file formats + Object module file output by 


assembler or compiler 
¢ Relocatable load module file 


+ Library file created using librarian 


3. Address/notation Hexadecimal only H8/300 Series: 


300HA*: 0-OFFFFFF 
Others: 0-OFFFF 


Range of specification varies with H8/500 Series: 0-OFFFF 
Saree mode) H32 Series: 0-OFFFFFFFF 
SH Series: 0-OFFFFFFFF 


4 Names of modules, Up to 32 characters 
units, sections, symbols 

5 Length of options or Up to 255 characters 
subcommands 

6 Number of modules, Max 65,535 Assumes no prior 
units, sections, export restrictions on memory of 
symbols, import system on which Linkage 
symbols Editor is executed. 


Note: * “300HA’” indicates the advanced mode of H8/300 Series. 
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Section 9 Object Format Conversion 


In order for the load modules output by the Linkage Editor to be input into an emulator or PROM 
programmer, they must first be converted to S-type object format using the Object Format 
Converter. 


9.1 Executing the Object Format Conversion 


The command line format for starting the Object Format Converter is as follows. 

envsA<Input file name>([A<output file name>] 

Command Name: The Object Format Converter is started up by specifying the command “cnvs.” 
Input File Name: The name of an absolute-format load module file to be input to the Object 
Format Converter is specified. Relocatable load module files cannot be specified. 

If the file type is omitted from the file name, the Object Format Converter automatically assumes 


this to be “abs” when it inputs the file. 


Output File Name: The name of the S-type object file to be output by the Object Format 
Converter is specified. If the file type is omitted from the file name, the Object Format Converter 
automatically assumes this to be “.mot” when it outputs the file. 


Examples of command line specification are given below. 
% cnvsAprogl.1lmdAprogl.sty sea e®D 
% cnvsAproglAprogl (RED ............ ) 


® File “prog1.lmd” is input, and file “prog1.sty” is output. 
@ File “progl.abs” is input, and file “prog1.mot” is output. 
The S-type object format is shown in figure 9-1. 
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(a) Header record 
“4 


ie 
Pao 
ry 


Load address Check sum *2 

Byte count *? File type (3 char.: 6 bytes) 
Record format Main file name 

Record header (8 char.: 16 bytes) 


(b) Data record 
(i) When load address is between 0 and OFFFF (hexadecimal) 


s 
a 
bl 


' y 
Load address (2 bytes) Check sum *2 
Byte count *! Data (max 16 bytes) 
Record format 
Record header 


(ii) When load address is between 10000 and OF FFFFF (hexadecimal) 


74 


| 

ie 

Ee) 
ry 


! 
Load address (3 bytes) Check sum *2 
Byte count ** Data (max 16 bytes) 


Record format 
Record header 


°3 


(iii) When load address is between 1000000 and OFFFFFFFF (hexadecimal) 


$|3 
ESE es codec es EES 
EY ys a pre Nee eEE! 


“4 


© 
xx] xx| 04] 
a 


“3 


Load address (4 bytes) Check sum *2 
Byte count *! Data (max 16 bytes) 
Record format 
Record header 


Notes: 1. The byte count is the number of bytes from the load address (or entry address) to check sum. 

. Check sum is the 1's complement of the result of adding the data values from the byte count 
to that before check sum, in byte units. 

. “LF” indicates the line feed code. 

. In PC system, there is "CR" (0D) before “LF” (0A). “CR® indicates carriage return code. 


Bo 


Figure 9-1 S-Type Object Format 
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(c) End record 


(i) When load address is between 0 and OFFFF (hexadecimal) 
°4 


s|9]0o 3 @ 
[2620] = exc vox on 
(ed el eee ee eet 


i 
Check sum *2 


Entry a“dress (2 bytes) 
Byte count *1 


Record format 
Record header 


(ii) When load address is between 10000 and OFFFFFF (hexadecimal) 
*4 


Re 
3] «xxx exe 
aa 


Entry address (3 bytes) Check sum *2 
Byte count *1 
Record format 
Record header 


(iii) When load address is between 1000000 and OFFFFFFFF (hexadecimal) 


4 


eo 
a oo 
== 


’ 
Entry address (4 bytes) Check sum *2 
Byte count *! 
Record format 
Record header 


The byte count is the number of bytes from the load address (or entry address) to the 
check sum. 

. The check sum is the 1's complement of the sum of the data values from the byte count 
to the byte before the check sum, in byte units. 

. "LF" indicates the line feed code. 

. In PC system, there is “CR” (0D) before “LF” (0A). "CR" indicates carriage return code. 


Figure 9-1 S-Type Object Format (cont) 
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9.2 Error Messages 


When errors are made in command specification, or when an error is detected during the 
conversion process, the Object Format Converter outputs error messages in the following format. 


f 


**xA <Error number>A<error message>[(<additional information>) ] 


| ist column 


A list of error messages is given below in table 9-1 in the following format. 


Error Number Error Message Additional Information 


Nature of Error 
Converter actions and corrective actions 
Notation used in table: —: No additional information 
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Table 9-1 Object Format Converter Error Messages 


301 


302 


303 


304 


305 


306 


307 


308 


309 


INVALID COMMAND PARAMETER — 


An improper command parameter was specified. 


Check the command parameters and re-execute. 

FILE NOT FOUND File name 
The specified file cannot be found. 

Check the directory and the specified file name, then re-execute. 
CANNOT OPEN FILE : File name 
File cannot be opened. 


acta hc ee 
Check the specified file name. If the file name is correct, the disk may be full, or there may 
be a disk hardware problem. After checking the problem, re-execute. 


CANNOT READ FILE File name 
File cannot be input. 


Check the specified file name. If the file name is correct, there may be a disk hardware 
problem. After checking the problem, re-execute. 


CANNOT WRITE FILE File name 
File cannot be output. 


a a a a ee ee 
Check the specified file name. If the file name is correct, the disk may be full, or there may 


be a disk hardware problem. After checking the problem, re-execute. 
CANNOT CLOSE FILE File name 
File cannot be closed. 


eee 
Check the specified file name. ff the file name is correct, the disk may be full, or there may 


be a disk hardware problem. After checking the problem, re-execute. 
ILLEGAL FILE FORMAT File name 

The specified file format is incorrect. 

Check the file contents, then re-execute. 

ILLEGAL FILE NAME File name 

An illegal file name was specified. 

Specify a legal file name. 

MEMORY OVERFLOW _ 

There is insutficient memory available for use by the Object Format Converter. 


Expand the memory or revise the user program, then re-execute. 
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Appendix A Example of Use of Linkage Editor 


In this sample application, the 11 object modules and one library file shown in table A-1 are input 
into the Linkage Editor. 


Table A-1 List of Input Files 


No. File Name Type of File 
main.obj Object module file 
init.obj 

cmndanl.obj 

emndpre.obj 

table.obj 

term.obj 

keyin.obj 

file.obj 


Ol@MINIOA;[al|spA]wlm]— 


printer.obj 


_ 
o 


display.obj 


wl 
= 


commu.obj 


= 
nN 


function.lib Library file 


Library file “function.lib” consists of the 14 modules listed in table A-2. 
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Table A-2 List of Modules in Library File 


z 
2 


Module Name 
mvdata 
upshft 


comp 


expr 


rmargin 


Imargin 
sum 


number 


O/DINI[O]/H/Alwl]rmo]— 


Zerosprs 


Oo 


ascbin 


11 binasc 


Linkage Execution: Input the following command to execute module linkage. In this example, 
subcommands are input from subcommand file “exlink.sub,” and execution is controlled by these 
subcommands. 


InkA-SUBCOMMAND=ex1ink. sub 


The contents of subcommand file “exlink.sub” are shown in figure A-1. 
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First Linkage Process 


form ; Relocatable Load Module 
input i ; Input "main.obj" 

input ini ; Input "init.obj" 

input emndanl ; Input “cmndanl.obj" 
input emndpre Input "“cmndpre.obj" 
input table ; Input "table.obj" 

input term ; Input "term.obj" 
library function Library "function.lib" 
output programl ; Output "programl.rel" 
print programl Print "“programl.map" 


Linkage Process 


programl.rel ; Input “programl.rel" 
keyin ; Input "“keyin.obj" 
file Input "file.obj” 
printer ; Input "printer.obj" 
display Input "display.obj" 
comm ; Input "comm.obj" 
function Library "function.lib" 
7 Sequence of Sections 
programl, program2, function, global, local, f_ local, stack_area 
example ; Output “example.abs" 
example ; Print "“example.map" 


Figure A-1 Subcommand File “exlink.sub” 


As figure A-1 shows, two linkage processes are carried out, using the multilinkage function. In 
the first linkage process, six object module files and the library file are input, and relocatable load 
module file “program1.rel” and linkage list “program1.map” are output. In the second linkage 
process, load module file “program1.rel” is re-input, and the remaining object module files are 
input. The output is absolute load module file “example.abs” and linkage list “example.map.” 


Linkage list, “program1.map” output in the first linkage process is shown in figure A-2. Linkage 
list “example.map” output in the second linkage process is shown in figure A-3. 
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H SERIES LINKAGE EDITOR Ver. 5.0B 


LINK COMMAND LINE 


lnk -subcommand=exlink. sub 


LINK SUBCOMMANDS 


First Linkage Process 


r ; Relocatable Load Module 
main ; Input “main.obj”" 

init ; Input “init.obj” 
emndanl ; Input “cmndanl.obj" 
emndpre ; Input "cmndprc.obj" 
table ; Input “table.obj" 

term ; Input "term.obj" 
function ; Library "function.lib" 
programl Output “programl.rel"” 
rogram Print "“programl.map" 


UNDEFINED SYMBOL (main. keyin) 
UNDEFINED SYMBOL (cmndpre. printer) 
UNDEFINED SYMBOL (cmndprc. file) 
UNDEFINED SYMBOL (cmndpre.keyin) 
UNDEFINED SYMBOL (cmndpre. commu) 
UNDEFINED SYMBOL (cmndpre. display) 
UNDEFINED SYMBOL (term. file) 


Figure A-2 Linkage List “program1.map” (Input Information) 
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H SERIES LINKAGE EDITOR Ver. 5.0B 


SECTION NAME START 


ATTRIBUTE : CODE NOSHR 


programl 


H'0000034a 


H'00000468 


H'0000055e 


H'000007e8 


* TOTAL ADDRESS * H'00000000 


ATTRIBUTE : DATA NOSHR 


local H'00000000 


H'00001e20 


H'00001e40 


H'00003c80 


H'000222c0 


* TOTAL ADDRESS * H'00000000 


ATTRIBUTE : DATA NOSHR 


global 


* TOTAL ADDRESS * H'00000000 


ATTRIBUTE : STACK NOSHR 


stack_area 


* TOTAL ADDRESS * H'00000000 


H'00000000 


H'00000000 


H'00000000 


LINKAGE EDITOR LINK MAP LIST 


END LENGTH 
UNIT NAME 


H'00000349 H'0000034a 
main 
H'00000467 H'0000011le 
init 
H'0O0005Sd H'O000000£6 

emndanl 
H'000007e7 H'0000028a 

emndpre 
H'0000091f H'00000138 

term 
H'0000091f H'00000920 


H'0000lelf H'00001e20 
main 
H'0000le3£ H'00000020 
init 
H'00003c7£ H'00001e40 

emndanl 
H'000222bf H'0001e640 

emndpre 
H'000222df H'00000020 

term 
H'000222df£ H'000222e0 


H'000015c£ H'000015d0 
table 
H'00001S5cf H'000015d0 


H'OOlelffF H'001e2000 
table 
H'OOlelfff H'001e2000 


MODULE NAME 


main 

initialize 
command_analize 
command _process 


terminate 


main 

initialize 
command_analize 
command_process 


terminate 


global_table 


global_table 


Figure A-2 Linkage List “program1.map” (Link Map List) 
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H SERIES LINKAGE EDITOR Ver. 5.0B 


*** LINKAGE EDITOR LINK MAP LIST 


SECTION NAME START - END LENGTH 
UNIT NAME 


ATTRIBUTE : CODE NOSHR 


function H'00000000 - H'0000001b H'0000001c 
comp 
H'0000001c - H'0000010f H'000000f4 
expr 
H'00000110 — H'00000163 H'00000054 
mvdata 
H'00000164 — H'00000193 H'00000030 
upshft 
* TOTAL ADDRESS * H'00000000 - H'00000193 H'00000194 


ATTRIBUTE : DATA NOSHR 


£_local H'00000000 — H'0000000b H'0000000c 
comp 
H'0000000c - H'0000011b H'00000110 
expr 
H'0000011c - H'0000011f H'00000004 
upshft 


* TOTAL ADDRESS * H'00000000 - H'0000011f£ H'00000120 


PAGE: 2 


Kae 


MODULE NAME 


compare string 
expression 
move_data_ string 


upshift_character 


compare_string 
expression 


upshift_character 


Figure A-2 Linkage List “program1.map” (Link Map List) (cont) 
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SYMBOL NAME 


emndanl 
emndpre 
emndtbl 
comp 
expr 
fltbl 
header 
init 
keybuf 
main 
mvdata 
prbuf 
recbuf 
stackarea 
term 
upshft 


H SERIES LINKAGE EDITOR Ver. 5.0B 


ADDR 


H'00000000 
H' 00000000 
H'000000c8 
H'00000000 
H'00000000 
H'000003c8 
H' 00000000 
H'00000000 
H'000001c8 
H'00000000 
H'00000000 
H'000014c8 
H'000013c8 
H'00000000 
H'00000000 
H'00000000 


KEK LINKAGE EDITOR EXTERNALLY DEFINED SYMBOLS LIST 


TYPE 


DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 
DAT 


kkk 


Figure A-2 Linkage List “program1.map” (Export Symbol List) 
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H SERIES LINKAGE EDITOR Ver. 5.0B PAGE: 1 
*** LINKAGE EDITOR UNRESOLVED EXTERNAL REFERENCE LIST *** 
: main.obj 


: main 
: main 


SYMBOL NAME 
keyin 


: emndpre.obj 


command_process 
: emndpre 


SYMBOL NAME 


comm 
display 
file 
keyin 
printer 


: term.obj 


: terminate 
: term 


Figure A-2 Linkage List “program1.map” (Undersolved Import Symbol List) 
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H SERIES LINKAGE EDITOR Ver. 5.0B 
LINK COMMAND LINE 


LINK SUBCOMMNADS 


; Second Linkage Process 


; 


input programl.rel ; Input "programl.rel" 
input keyin ; Input "keyin.obj" 
input file 7 Input "file.obj" 
input printer ; Input "printer.obj" 
input display 7 Input “display.obj" 
input commu 7 Input “commu.obj" 
library function ; Library "function.lib" 
3; Sequence of Sections 
start program1, program2, function, global, local, f_local,stack_area 
output example : tput "“example.abs" 
print example ; Print “example.map" 
exit 


Figure A-3_ Linkage List “example.map” (Input Information) 
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H SERIES LINKAGE EDITOR Ver. 5.0B PAGE: 1 


eee LINKAGE EDITOR LINK MAP LIST *** 


SECTION NAME 


ATTRIBUTE : 
programl 


* TOTAL ADDRESS * 


ATTRIBUTE : 
program2 


* TOTAL ADDRESS * 


ATTRIBUTE : 
function 


START 


CODE NOSHR 


H'00000000 


H'0000034a 


H'00000468 


K'0000055e 


H'000007e8 


H'00000000 


CODE NOSHR 


H'00000920 


H'00000b20 


H*'00000c48 


H'00000d4a 


H'00000e62 


H'00000920 


CODE NOSHR 


H'00001128 
H'00001144 
H'00001238 
H'0000128c 
H'000012be 
H'00001344 


H'00001374 


END LENGTH 
UNIT NAME 
H'00000349 H'0000034a 


main 
H'00000467 H'00000lie 
init 
H'0000055d H'oooo0o0Oof6 
emndani 
H'0000028a 
emndpre 
#H'00000138 
term 
H'00000920 


H'000007e7 
H'0000091f 


H'0000091f£ 


H'O0000bif H'00000200 
keyin 
H'00000c47 H'00000128 
file 
H'00000¢49 H'00000102 
printer 
H’00000118 
display 
H'000002c6 
comm 
H'00000808 


H'00000e61 
H'00001127 


H'00001127 


H'00001143 B'0000001ic 
comp 
H'00001237 H' 0000004 
expr 
H'0000128b H'00000054 
mvdata 
H'00000030 
upshft 
K' 00000088 
lmargin 
H'00000030 
number 
H'00000080 
rmargin 


H'000012bb 


H'00001343 


H'00001373 


H'000013£3 


MODULE NAME 


programl 
programl 


programl 


programl 


programl 


input_keyboard 
file io 

output_printer 
display _console 


communication 


programl 
programl 
programl 
programl 
left_margin 


numbering _items 


right_margin 


Figure A-3 Linkage List “example.map” (Link Map List) 
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SECTION NAME 


H SERIES LINKAGE EDITOR Ver. 5.0B 


ne LINKAGE EDITOR LINK MAP LIST 


START 


ATTRIBUTE : CODE NOSHR 


function 


* TOTAL ADDRESS * 


ATTRIBUTE 
global 


* TOTAL ADDRESS * 


ATTRIBUTE : 
local 


H'000013£4 


H'0000140c 


H'000014c8 


H'00001534 


H'00001574 


H'00001640 


H'C0001648 


H'00001128 


: DATA NOSHR 


H'00001658 


H'00001658 


DATA NOSHR 


H'00002c28 


H'00004a48 


H'00004a68 


H'000068a8 


H'00024ee8 


H'00024f08 


H'00025128 


H'00025308 


H'0002544c 


~ END 


- H'0000140b 
~ H'000014c7 
- H'00001533 
- H'00001573 
- H'0000163£ 
~- H'00001647 
- H'00001657 


- H'00001657 


~ H'00002c27 


- H'00002c27 


- H'00004a47 
- H'00004a67 
- H'000068a7 
- H'00024ee7 
- H'00024f£07 
- H'00025127 
~ H'00025307 
~ H'0002544b 


- H'0002554f 


LENGTH 
UNIT NAME 


H'00000018 
sum 
B'000000be 
zerosprs 
H'0000006c 
ascbin 
H'00000040 
binasc 
H'000000cc 
envbed 
H'00000008 
dos 
H'00000010 
portio 
H'00000530 


H'000015d0 
table 
H‘'00015d0 


H'00001e20 
main 
H*00000020 
init 
H'00001e40 
emndanl 
H'0001e640 
emndpre 
H'00000020 
term 
H'00000220 
keyin 
H'000001e0 
file 
H'00000144 
printer 
H'00000104 
display 


wee 


MODULE NAME 


sum_items 
zero_suppress 
ascii_to_binary 
binary _to_ascii 
convert _to_ bed 
interface_of_dos 


interface_of_ port 


programl 
rograml 
programl 
programl 
input_keyboard 
file io 
output_printer 


display console 


Figure A-3 Linkage List “example.map” (Link Map List) (cont) 
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SECTION NAME 


ATTRIBUTE : 
local 


* TOTAL ADDRESS * 


DATA NOSHR 


H'00025550 


H'00002¢c28 


ATTRIBUTE : DATA NOSHR 


£_local 


* TOTAL ADDRESS * 


stack_area 


* TOTAL ADDRESS * 


ATTRIBUTE: STACK NOSHR 


H'00025714 


H'00025720 


H'00025830 


H'00025834 


H'00025844 


H'00025848 


H' 00025858 


H'0002587c 


H'00025884 


H'00025888 


H'00025714 


H'000258d0 


H'000258d0 - H'002078cf 


H SERIES LINKAGE EDITOR Ver. 


- H'0002S71£ 


- #'00025847 
~ H'00025857 
- H'0002587b 
- H'00025883 
- H'00025887 
~- H'000258cf 


- H'000258cf 


~ H'002078cf 


5.0B 


LINKAGE EDITOR LINK MAP LIST 


- END LENGTH 


UNIT NAME 


- H'00025713 H'000001¢c4 
comm 


- H'00025713 H'00022aec 


H'0000000c 
comp 
H'00000110 
expr 
- H'00025833 H'00000004 
upshft 
H'00000010 
lmargin 
H'00000004 
number 
H'00000010 
rmargin 
H'00000024 
zerosprs 
H'00000008 
ascbin 
H'00000004 
binasc 
H'00000048 
envbed 
H'000001be 


~ H'0002582f 


- H'00025843 


H'001e2000 
table 
H'001e2000 


MODULE NAME 


communication 


programl 
programl 
programl 
left_margin 
numbering items 
right_margin 
zero_suppress 
ascii_to_binary 
binary_to_ascii 


convert_to_bed 


programl 


Figure A-3 Linkage List “example.map” (Link Map List) (cont) 


114 


HITACHI 


H SERIES LINKAGE EDITOR Ver. 5.0B 


LINKAGE EDITOR EXTERNALLY DEFINED SYMBOLS LIST 


SYMBOL NAME 


ascbin 
binasc 
emndanl 
emndpre 
emndtbl 
envbed 
comm 
comp 
display 
dos 
expr 
file 
fltbl 
header 
init 
keybuf 
keyin 
lmargin 
main 
mvdata 
number 
portio 
prbuf 
printer 
recbuf 
rmargin 
stackarea 
sum 
term 
upshft 
zerosprs 


Figure A-3 Linkage List “example.map” (Export Symbol List) 


ADDR 


H'000014c8 
H'00001534 
H'00000468 
H'000005S5e 
H'00001720 
H'00001574 
H'00000e62 
H'00001128 
H'00000d4a 
H'00001640 
H'00001144 
H'00000b20 
H'00001a20 
H'00001658 
H'0000034a 
H'00001820 
H'00000920 
H'000012be 
H'00000000 
H'00001238 
H'00001344 
H'00001648 
H'00002b20 
H'00000c48 
H'00002a20 
H'00001374 
H'000258d0 
H'000013£4 
K'000007e8 
H‘'0000128c 
H'0000140c 
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A 
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E 
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Preface 


This manual describes how to use the H Series Librarian. The manual is divided into the following 
eight sections. 


Sections 1 and 2 Librarian functions 


Section 3 Executing the Librarian 
SECHON A  sscxccscccrsiscunsxcsscssssvensszesseusseass Librarian options and subcommands 
Section 5 Input to the Librarian 


Section 6... Output from the Librarian 
Error messages 
Restrictions 

ADDONGINGA ws scresscrceersscaseseremerccnrerecenss Examples of Use of Librarian 


Installation of the Librarian is covered in the Installation Guide supplied with the Librarian. 


Refer to the following user's manuals for additional information on the other support tools in the 
H series cross system. 


H Series Linkage Editor User's Manual 
H8/300 Series Cross Assembler User's Manual 
H8/500 Series Cross Assembler User's Manual 
H32 Series Cross Assembler User's Manual 
SH Series Cross Assembler User's Manual 
H8/300 Series C Compiler User's Manual 
H8/500 Series C Compiler User's Manual 

H32 Series C Compiler User's Manual 

SH Series C Compiler User's Manual 
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Notes: 
The following symbols have special meanings in this manual. 
<item> : <specification item> 
{ } : One of the items between the brackets is to be selected. 
[ ] : The enclosed item is optional (i.e., can be omitted). 
: The preceding item can be replaced. 
A : Blank space(s) or tab(s) 


: Press the Return (Enter) key. 


UNIX is an operating system administrated by the UNIX System Laboratorics (United States). 
MS-DOS is an operating systcm administrated by the Microsoft Corporation (United States). 
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Section 


Section 2. Librarian Functions 


2.1 
viv) 
2:3 
2.4 


Section 3. Executing the Librarian 


3.1 
3.2 
33 


3.4 


Section 4. Librarian Options and Subcommands 


4.1 
4.2 
4.3 


4.4 


4.5 


Contents 


1. Overview 


Creating Library Files 

Editing Existing Library Files 
Extracting Modules from a Library File.... 
Displaying the Contents of a Library File.... 


Command Line Format. 
Executing by Command Line 
Executing by Subcommands... 
3.3.1 Executing in Interactive Mode 


3.3.2 Executing from a Subcommand File... 
Terminating Librarian Operations 


Option and Subcommand Formats 
List of Options and Subcommands. 
File Control. ssisinsssseseansceepiconssscasswosdvesnevevtsdavsstausausspasstecvesaatestusvacsece 
4.3.1 LIBRARY — Specifies the library file to be edited. 
4.3.2 OUTPUT — Specifies an output library file 
Executlon Control .sjcscesces.sssusssacconseavexsassavaviausesciasessncostesvesssecasas 
4.4.1 _SUBCOMMAND — Specifies a subcommand file . 
4.4.2 CREATE — Creates a library file. 
4.4.3. ADD — Adds modules 
4.4.4 REPLACE — Replaces modules 
4.4.5 DELETE — Deletes modules 
4.4.6 EXTRACT — Exwacts modules............:.csse0- 
4.4.7 END — Specifies end of subcommand input ... 
4.4.8 | EXIT — Specifies end of Librarian operations 
44.9 ABORT — Aborts librarian operations ... 
List Display. 

4.5.1 LIST — Displays contents of a library file 
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Section 5. Input to the Librarian 
Si MERE Rac an De  inicrcen csesncen cnsnnnonenshlnsinradicinte ddan cova eater escheat gas eas aang 
5.2 Relocatable Load Module Files... 
5.3 Library Files 


Section 6. Output from the Librarian 
6.1 Library Files .... 
6.2 Librarian Lists.. 


6.3 Console Messages 


Section 7. Error Messages 


Section 8. Restrictions 


Appendix A Examples of Use of Librarian 
A.1 Librarian Execution by Command Line 


A.2 Librarian Execution by Subcommands. 
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Section 1. Overview 


A program is usually developed by dividing it into functional modules and creating a separate 
source program for each module. Next, each source program module is compiled or assembled to 
create an object module. The object modules are then linked together using a linkage editor, 
resulting in an executable program. 


The H Series Librarian introduced in this manual (hereafter called the Librarian) plays a vital role in 
this process. It brings together the many object modules output by the C compiler and assembler, as 
well as relocatable load modules output by the linkage editor, to make library files. 


The Librarian provides the following advantages. 


Simplified Module Management: The many modules making up a program (including relocatable 
load modules as well as object modules) are stored in a library file for the particular program. They 
can then be dealt with all at once. Moreover, it is possible to create generic library files that can be 
used later to streamline the creation of other programs. 


A library file can be edited by adding, deleting, or replacing individual modules. In this way the 
modules can be kept up to date. 


Enhanced Linkage: The Linkage Editor can search library files to find, extract, and link modules 
that define unresolved import symbols. Use of the library files thus makes linkage editing more 
efficient. 
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Section 2. Librarian Functions 
2.1 Creating Library Files 
This function makes it possible to create new library files, and to enter object modules output by the 


C compiler or assembler as well as relocatable load modules output by the linkage editor. 
Figure 2-1 is an illustration of the library file creation concept. 


Entered modules New library file 


Module A 
Module A 


Creation 


Module 8 c—» Mode 8 
Module C 
Module C 


Figure 2-1. Creating a New Library File 


2.2 Editing Existing Library Files 
Modules can be added to, deleted from, or replaced in existing library files. 


Adding Modules: Modules can be added to already existing library files. The concept of module 
addition is illustrated in Figure 2-2. 
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Existing library file Edited library file 


Module B 


Addition Module C 
Module D 


Figure 2-2. Adding a Module 


Deleting Modules: Unnecessary modules can be deleted from existing library files. Figure 2-3 
illustrates the module deletion concept. 


Existing library file Edited library file 


Module B 


Module B 
P< aes 


Figure 2-3. Deleting a Module 


Deletion 


Replacing Modules: Modules in existing library files can be replaced with new modules. The 
concept of module replacement is illustrated in Figure 2-4. 
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Existing library file Edited library file 


Module A Module A 
Replacement 


— ‘ 
— ‘ 


Figure 2-4. Replacing a Module 


2.3 Extracting Modules from a Library File 


Modules can be extracted from existing library files and used to create new library files. The 
concept of module extraction is illustrated in Figure 2-5. 


Existing library file New library file 


Extraction 


Figure 2-5. Extracting Modules 
2.4 Displaying the Contents of a Library File 
A librarian list giving information about the modules and export symbols in a library file can be 
output to a standard output device or a list file. A librarian list tells when the library file was 
created and when it was last revised, indicates when each module was stored, and gives the names 


of export symbols and other useful information. 


For further details, see section 6.2, Librarian Lists. 
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Section 3. Executing the Librarian 


To execute the Librarian, first start the Librarian by entering a command line. The command line 
specifies the name of the library file to be edited and various options, which give instructions to the 
Librarian. If these instructions are sufficient, the Librarian can be executed using the command line 
alone. If further instructions are needed, they can be given in subcommands. 


Command Line Execution: The Librarian can be executed simply by specifying a library file and 
options on the command line. The method is useful when library editing is relatively 
straightforward. 


Subcommand Execution: The Librarian can also be executed by entering both a command line 
and subcommands. The subcommands specify input and output files and parameters that control 
the Librarian. This method is useful for specifying a large number of files or modules, or for editing 
two or more library files together. Subcommands can be entered interactively, or from a 
subcommand file. Details are given in section 3.3, Executing by Subcommands. 


3.1 Command Line Format 
The following format is used for the Librarian command line. 


UNIX System: 
Ibr[A[<library file name>][[A]-<option name>[[A]-<option name>...]]](RET) 


MS-DOS system: 
Ibr[A[<library file name>}{[A]/<option name>[[A]/<option name>...]]](RET) 


Command Name: “Ibr” is the command that starts the Librarian. 


Library File Name: To edit or extract modules from an existing library file, type the name of the 
library file in the command line. 


Option Names: Each option name must start with a hyphen (-) at UNIX system or with a slash () 
at MS-DOS system. One or more spaces or tabs may also be used to separate an option name from 


a preceding option name or library file name, but these spaces or tabs are not required. Option 
names are described in detail in section 4, Librarian Options and Subcommands. The Librarian 
edits the library file according to the order in which the options are specified. 
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Specifying the Mode of Execution: The content of the command line determines whether the 
Librarian will be executed by the command line specifications only, or by subcommands. See 
Table 3-1. 


The library file name and each option name must be specified in 128 characters or less (not 
including the final carriage return). 


Table 3-1. How Command Line Specification Determines the Form of Execution 


Option Specification 
No Option SUBCOMMAND CREATE Option Option Other than 
Library File Name Specified Option Specified Specified CREATE or 
Specification SUBCOMMAND 
Specified 
Library file name — = — Executed by 
specified specifying 
command line 
No library file name Executed by Executed by Executed by _ 
specified specifying specifying specifying 
subcommands subcommands command line 
Notes: 1. For SUBCOMMAND and CREATE options, see section 4, Librarian Options and 


Subcommands. 
2. The combinations of option and library file names indicated by dashes (—) are not permitted. 


An error will occur, and the librarian will not be executed. 


3.2 Executing by Command Line 


With this method, the Librarian is executed according to the information specified in the command 
line alone. Editing procedures and other conditions are specified to the Librarian in the form of 
options. When the editing process is straightforward and simple, command line specification is 
sufficient for creating or updating a library. Examples of execution by command line are given 
below. 
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EXAMPLE 1 (UNIX system): 


% \brA-CREATE=syslib.lib-ADD=0bj00.obj,pre.lib RED 


Se ee 


1 2 


1 Creates a new library file named syslib.lib. 
2 Adds the modules in object module file obj00.obj and library file prg.lib to syslib.lib. 


The CREATE option by itself will not create a library file unless modules are added using the ADD 
option. 


EXAMPLE 2 (MS-DOS system): 
% IbrAsyslib.lib/ADD=0bj00.0bj/DELETE=mod1(RET) 


1 2 3 


1 Designates library file syslib.lib as the file to be edited. 
2 Adds the module in object module file obj00.obj to syslib.lib. 
3 Deletes existing module mod1 from syslib.lib. 


3.3 Executing by Subcommands 


Since the number of characters that can be typed on the command line is limited, the command line 
may not be able to accommodate a large number of specifications. In such cases, subcommands are 
used to execute the Librarian. Subcommands can be input interactively, one at a time, from the 
keyboard or other standard input device. Alternatively. a subcommand file consisting of a group of 
subcommands can be created in advance, and subcommands can be input from this subcommand 
file. 


3.3.1 Executing in Interactive Mode 


When no library file is specified in the command line and there are no option specifications, 
execution proceeds in interactive mode. A colon (:) appears on the screen as a prompt, indicating 
that the Librarian is waiting for a subcommand to be input. In this way you can enter the necessary 
subcommands. This method is useful when the number of subcommands is relatively small, or 
when you want to check Librarian lists as you enter the subcommands. 


HITACHI 


An example of execution by interactive input of subcommands is given below. Functions of the 
subcommands listed here are detailed in section 4, Librarian Options and Subcommands. 


EXAMPLE: 

% \br (RET) wl 
CREATEAprg.lib (RET) wd 
ADDAmain.obj (RET) . 23 
ADDAsend.obj,receive.obj,exchange.obj | 
ADDaAaccount.obj (RET) 5 
LISTA(S) 6 

my 


EXIT (RET) 


Starts the Librarian in interactive mode. 

Creates a new library file named prg.lib 

Adds the module in main.obj to prg.lib. 

Adds the modules in send.obj, receive.obj and exchange.obj to prg.lib. 

Adds the module in account.obj to prg.lib. 

Outputs a librarian list, including symbol information, to the standard output device. 


Naw BwWnN 


Terminates the Librarian operation. 
3.3.2 Executing from a Subcommand File 


This method uses a subcommand file that was created in advance and that contains the 
subcommands necessary for Librarian operations. This subcommand file is then specified on the 
command line as a parameter of the SUBCOMMAND option. This method is useful when many 
subcommands must be specified, or when the same editing process is carried out repeatedly. It 
eliminates the need to input subcommands from the keyboard or other standard input device each 
time. 


Use an editor to create the subcommand file. An example of execution from a subcommand file is 


given below. Functions of the subcommands listed here are detailed in section 4, Librarian Options 


and Subcommands. 
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% \brA-SUBCOMMAND=prglib.sub (RET) oe | 


Contents of subcommand file prglib.sub: 


CREATEAfunction.lib Ses 
ADDAsin.obj,cos.obj,tan.obj a3 
ADDaAasin.obj,acos.obj,atan.obj 4 
ADDAhsin.obj,hcos.obj,htan.obj «iD 
ADDAlog.obj,log10.obj 6 

EXIT 7 

1 Starts the Librarian and inputs subcommands from subcommand file prglib.sub. 

2 Creates a new library file function.lib. 

3 Adds the modules in object module files sin.obj, cos.obj and tan.obj to function. lib. 

4 Adds the modules in object module files asin.obj, acos.obj and atan.obj to function_lib. 
5 Adds the modules in object module files hsin.obj, hcos.obj and htan.obj to function.lib. 
6 Adds the modules in object module files log.obj and log10.obj to function.lib. 

7 Terminates Librarian operations. 


3.4 Terminating Librarian Operations 


When the Librarian terminates operations, it gives the system a return code indicating an error level. 
The return code can be used to control the execution of a command file. The error levels and their 
return codes are: 


UNIX system: 
Normal completion 
Waming 

Error 

Fatal error 


- Fe OO 


MS-DOS system: 
Normal completion 
Warming 

Error 


& NO °C 


Fatal error 
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Section 4. Librarian Options and Subcommands 


Options and subcommands tell the Librarian what editing operations to perform. The three main 
functions of options and subcommands are file control, execution control, and list display. These 
functions can be used individually or in combination to create and edit library files. 


Options and subcommands have the same names and equivalent functions, but are specified in 
different formats. Moreover, there are some specifications which can be made only with options, 
and others only with subcommands. Sections 4.1, Option and Subcommand Formats, and 4.2, List 
of Options and Subcommands, must accordingly be read carefully. Option and subcommand 
functions are outlined below. 


File Control Functions: File control functions indicate the name of the library file to be edited, or 
the name of a library file to which extracted modules are to be output. 


Execution Control Functions: Execution control functions instruct the Librarian to perform 
editing operations, or terminate its processing. These functions are used, for example, to input 


subcommands from a subcommand file, to create a new library file, or to update a library file. 


List Display Functions: List display functions are used to display information such as names of 
modules stored in a library file, or export symbol names. 


Note: The examples are written for UNIX system, please write slash (/) instead of hyphen (—) for 
MS-DOS system and write all options and commands in capital letters. 
4.1 Option and Subcommand Formats 


Each option or subcommand consists of a name and parameters. which together must not exceed 
128 characters. 


Option and Subcommand Structure: Options and subcommands differ as to the way of 
separating the name from the parameters. Options use an equals sign (=), while subcommands use 
one or more spaces or tabs. 


Option format 


<Name>=<parameters> 
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Subcommand format 


<Name>A<parameters> 
EXAMPLES: 
OUTPUTS NOR sscc aves iscecscaccsssnesssscpsenscteced option 
OUTRUTAIBE, ...nccenceensasnsecsesscisaonis subcommand 


In these examples, OUTPUT is the name, and Ibf is the parameter. 

(a) Name 

The name gives the name of the option or subcommand. 

(b) Parameters 

The parameters give the names of files,*! module,*2 etc. on which the option or subcommand 
operates. There are different requirements and methods of specification depending on the type of 
option or subcommand. For details, refer to section 4.3, File Control, section 4.4, Execution 
Control, and section 4.5, List Display. 

Notes: 


1. A file name consists of three parts: the path name, main file name, and file type. 


If the file type is omitted, a file type is assumed as follows. 


Etbraty! Ble ssccssccessussvvescessvnsvssasevessesscestass lib 
OBJEC MOM UIE NE i sisi savcccarcrsvinensverratins Obj 
Relocatable load module file .................. -obj 
Subcommand file -sub 
List file..... st 


2. A module name is the name defined in an object module or relocatable load module. In 
module names, capital letters are distinguished from small letters. The pairs of names 
below, for example, are treated as different names. 
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EXAMPLES: modull ~<#————-® MODUL1 


abcde ~<#————®  Abcde 


Continuation Specification in a Subcommand: When a subcommand is too long to be specified 
on one line, a continuation specifier is used. This consists of an ampersand (&) at the end of the 
line. It must always be placed between two parameters; if it is placed within a parameter, it will not 
be treated as a continuation specifier. Also, if a character (including a space or tab) is typed after 
the ampersand, an error will occur and the subcommand will not be continued. 


In interactive input of subcommands, a hyphen (-) appears as a prompt for further input after 
continuation has been specified. 


EXAMPLES: 


-  obj01.0bj02 RED ee 


ADDAobj00.lib(mod0,mod1),ob& (RET) 


aa Specifying continuation 


in the middle of a 
parameter occurs in 
error. 


Continuation specifier 


A subcommand line in a subcommand file can be continued in the same way. The line after the line 
with the continuation specifier becomes the continuation line. 
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EXAMPLE: 
Subcommand file 


DELETEAsub1,sub2,& (RET) 


Continuation specifier 


sub3 (RET) , os 
SS — <I$—_—_—_—— Continuation line 


Specifying Comments in a Subcommand File: A comment specifier is used to place notes or 
other comments in a subcommand file. The specifier is a semicolon (;) placed on a subcommand 


line, indicating that the rest of the line is a comment. If the semicolon follows a subcommand name 
or parameter, it must be separated by at least one space or tab. 


If the semicolon is placed at the beginning of a subcommand line, the entire line is treated as a 
comment. 


EXAMPLES: 


; EXAMPLE OF LIBRARIAN SUBCOMMAND 

... the entire line is a comment. 

LIBRARY<AsyslibA; INDICATES LIBRARY FILE 

... INDICATES LIBRARY FILE is a comment. 

ADDAmodule.obj;abc 

.. module.obj;abc is treated as a single parameter 
abc is not treated as a comment. 
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4.2 List of Options and Subcommands 
There are eight options and eleven subcommands, as listed in Table 4-1. 
Table 4-1. List of Options and Subcommands 


No. Type Name Function Opt. Sub. Section 


1 File control LIBRARY Specifies the library file to be No Yes 4.3.1 
edited 

QUTPUT Specifies an output library file Yes Yes 4.3.2 

2 Execution SUBCOMMAND Specifies a subcommand file Yes No 4.4.1 

control CREATE Creates a library file Yes Yes 4.4.2 

ADD Adds modules Yes Yes 4.4.3 

BEPLACE Replaces modules Yes Yes 4.4.4 

DELETE Deletes modules Yes Yes 44.5 

EXTRACT Extracts modules Yes Yes 44.6 

END End of subcommand input No Yes 4.4.7 

EXIT End of Librarian operations No Yes 448 

ABORT Aborts Librarian operations No Yes 449 

3 List LIST Displays contents of library file Yes Yes 4.5.1 
display 


Notes: 1. The underlined letters of a name are the shortest permissible abbreviated form. 
2. The Opt. and Sub. columns indicate whether a name is available as an option or 
subcommand. 


Abbreviating Option and Subcommand Names: Names of options and subcommands may be 
abbreviated to the point where the name can still be distinguished from other names. As an 
example, consider the name EXTRACT. 


E ... Cannot be distinguished from EXIT or END, so an error occurs. 
EX ... Cannot be distinguished from EXIT, so an error occurs. 
EXT .. Recognized as EXTRACT. 
EXTRA ... Recognized as EXTRACT. 
EXTRACT .. Recognized as EXTRACT. 
EXTRACTS ... No such name, so an error occurs. 
14 
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Interrelation among Different Options and Subcommands: Once an option or a subcommand 
has been specified, other options or subcommands with conflicting functions cannot be specified. 
This interrelationship is shown in Table 4-2. 


Table 4-2. Interrelation among Options and Subcommands 


Later Specification 

2 

= > wy w be fs 
Option/ 255 2 #8 § 3228 8 8 
Subcommand 
SUBCOMMAND x x x x x x x x x x x 
LIBRARY x e) ie) Oo (e) .e) .e) oO ° ° 
CREATE x x x Oo #60 O° x x 12) ° O° 1) 
ADD x x x Oo oO O° x x 1) Oo Oo ce) 
REPLACE x x x Oo 9 :e) x x ie) Oo Oo ce) 
DELETE x x x Co Oo .e) x x .e) Oo os O° 
EXTRACT x x x x x x © ie) ° Oo Oo ie) 
OUTPUT x x x x x x (@) x e) 1°) e) Oo 
LIST x x x Oo Oo e) 1) 1) 3° Oo Oo ° 
END x O° O° x x x x x x x fe) ro) 
EXIT x x x x x x x x x x x x 
ABORT * x x x x x x x x 4 x x 


©: Later specification enabled. 


x: Later specification disabled, since it conflicts with already specified option or subcommand. 
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EXAMPLES: 


% \brA-SUBCOMMAND=funlib.sub-LIST (RET) 


This results in an error since no other option can 
be specified after a SUBCOMMAND option. 


% \br (RET) 
LIBRARY Afunclib.lib (RET) 


CREATEAnewlib.lib (RET) —~———— A CREATE subcommand cannot be specified 
after a LIBRARY subcommand. An error occurs, 
and the CREATE subcommand is ignored. 


END (RET) 


LIST (RET) <¢——____________ Specifying a LIST subcommand after an End 
subcommand, occurs in an error. After END, only the 


EXIT RED LIBRARY, CREATE, EXIT or ABORT subcommand 
is valid. 
16 
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In the following sections, the format below is used to describe each option and subcommand. 


Heading for each-option or 
—a subcommand 


Section Section number, and 
number heading for option or 
subcommand 


Option or subcommand 

name, and format for 
specifying parameters 

The underlined part of the name 
is the shortest abbreviated form 


Format Name Option Subcommand 


Parameters 


Function Summary of option or 
subcommand functions 


Explanation Detailed description of 
functions and restrictions 


Examples Examples of option or 
subcommand specifications 
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LIBRARY 


4.3 File Control 


4.3.1 LIBRARY — Specifies the library file to be edited. 


Format Name LIBRARY Option Subcommand 
No Yes 


Parameters <Library file name> 


Function Specifies an existing library file for editing. 


Explanation (1) This subcommand is specified at the beginning of an editing operation that 

edits an existing library file or extracts modules from an existing library file. 

(2) Only a library file created by this Librarian can be specified 

(3) When no file type is specified as part of the library file name, the type is 
assumed to be .lib. 

(4) This subcommand cannot be used together with the CREATE subcommand, 
which specifies creation of a new library file. 

(5) If, as the result of editing an existing library file, the number of modules 
becomes zero, the library file will not be updated. 

(6) The access right to the updated library file is the same as the access right to a 
newly created file. Note that the access right prior to the update is not 
preserved. 


Examples LIBRARYAsyslib 
Specifies editing of the library file syslib.lib. 
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OUTPUT 
4.3.2 OUTPUT — Specifies an output library file. 
Format Name QUTPU Option Subcommand 
Yes Yes 
Parameters Option <Library file name> 


Subcommand  <Library file name> [ ea} 


Function Specifies a library file for output of extracted modules. 


Explanation (1) Specify the OUTPUT option or subcommand whenever a module is to be 
extracted from an existing library file. 
(2) Specify a new library file name. When no file type is specified as part of the 
library file name, the type is assumed to be .lib. 
(3) The attribute (S) or (U) is assigned to the output file. If unspecified, the 
attribute is assumed to be (U). 
(S) ... System library 
(U) ... User library 
This attribute determines the order of priority in which library files are 
searched by the Linkage Editor. A user library has higher search priority. The 
(S) and (U) parameters cannot be included when OUTPUT is specified as an 
option. 
(4) OUTPUT may be specified either before or after the EXTRACT option or 
subcommand, which specifies extraction of modules. 
(5) OUTPUT cannot be used together with the CREATE, ADD, DELETE, or 
REPLACE options or subcommands. 
(6) When the number of extracted modules is zero, the library file specified by the 
OUTPUT option or sub-command is not created. 


Examples —OUTPUT=PROG86 
Modules extracted using the EXTRACT subcommand will be output as a user 
library to a file named prog86.lib. 
OUTPUTAclib.o(S) 
Modules extracted using the EXTRACT subcommand will be output as a 
system library to a file named clib.o. 
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SUBCOMMAND 


4.4 Execution Control 


4.4.1 SUBCOMMAND -— Specifies a subcommand file. 


Format Name SUBCOMMAND Option Subcommand 
Yes Yes 


Parameters <Subcommand file name> 


Function * Inputs subcommands from a specified file. 


Explanation (1) Inputs and processes subcommands from a specified subcommand file one at a 
time. 
(2) When an EXIT subcommand or the end of the subcommand file (EOF) is 
detected, Librarian operations end. 
(3) When no file type is specified as part of the file name, the type is assumed to 
be .sub. 


(4) ASUBCOMMAND option cannot be specified more than once, or used 
together with other options. 


Examples —SUBCOMMAND=makelib 


Subcommands are input from the subcommand file makelib.sub for use in 
editing a library file. 
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CREATE 
4.4.2 CREATE — Creates a library file. 
Format Name CREATE Option Subcommand 
Yes Yes 
Parameters Option <Library file name> 


Subcommand <Library file name> | | 


\ 


Function Creates a new library file. 


Explanation (1) Specified at the beginning of a group of options or subcommands ending with 
END or EXIT. 
(2) Specify a new library file name. When no file type is specified as part of the 
library file name, the type is assumed to be .lib. 
(3) The attribute (S) or (U) is assigned to the output file. If unspecified, the 
attribute is assumed to be (U). 
(S) ... System library 
(U) ... User library 
This attribute determines the order of priority in which library files are 
searched by the Linkage Editor. A user library has higher search priority. The 
(S) and (U) parameters cannot be included when CREATE is specified as an 
option. 
(4) CREATE cannot be used together with the LIBRARY subcommand. 
(5) Ifthe number of modules is zero, no library file is created. 


Examples -—CREATE=userlib.lib 
Creates userlib.lib as a new user library. 


CREATEAsislib(S) 
Creates sislib.lib as a new system library. 


CREATEAdatax 
Creates datax.lib as a new user library. 
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ADD 


4.4.3 ADD — Adds modules. 


Format Name ADD Option Subcommand 
Yes Yes 


Parameters Option <Object module file name> 


<Relocatable load module file name>» [,...] 
<Library file name> 


Subcommand / <Object module file name> 
<Relocatable load module file name> L.-J 
<Library file name>[(<module name>[,...])] 
Function Adds modules from specified files to a library file. 


Explanation (1) ADD is used to store modules in a new library file, or add modules to an 
existing library file. 

(2) When only a file name is specified, if no file type is specified, the type is 
assumed to be .obj. When a module name is specified after a file name, the 
file is assumed to be a library file, so if no file type is specified, the type is 
assumed to be .lib. 

(3) When only certain modules from a library file are to be added, specify the 
module names after the library file name. Up to 10 module names may be 
specified. However module names can not be included when ADD is 
specified as an option. 


EXAMPLE: ADD Ibf (m1,m2,.m3) 


t A Module names 
Library file name 


(4) When modules in a library file are specified, the specified module names are 
sorted in alphabetical order and the modules are added in that order. They are 
not added in the order in which specified. 


EXAMPLE: ADD Ibf (e, a, d, c, b) 
5, 1, 4, 3, 2... Order in which modules are 
added 
(Continued on next page) 
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Explanation (5) When the names of modules in a library file are not specified, all modules in 


(cont) 


Examples 


(6) 


(7) 


(8) 


(9) 


the library file are added. 


EXAMPLE: ADD Ibf.lib 


he itrary file name 


When a module to be added has the same name as a module already in the 
library file being edited, or when an externally defined symbol defined in the 
module to be added has the same name as an externally defined symbol in the 


library file being edited, a warning message is displayed and the module is not 
added. 

The name of an object module or relocatable load module is the name defined 
in the module. The LIST option or subcommand is a convenient way of 
confirming which modules are stored in a library file. 

ADD cannot be used together with EXTRACT or OUTPUT options-or 
subcommands. 

Errors will occur and the parameters after the error occurs will not be 
processed when: 

(a) A specified file does not exist. 

(b) A specified module does not exist in a library file. 

(c) The content of the specified file is invalid. 

(d) The number of modules to be stored exceeds 32,767. 

(e) Memory capacity is insufficient to add more modules. 

(f) | The number of input files exceeds 12. 


-ADD=mod1,mod2,modx.o 


Adds all modules from the object module files mod1.obj, mod2.obj and 
modx.0o. 


ADDaAiofnc(keyin,crtout) 


Adds the two modules keyin and crtout from the library file iofnc.lib. 


ADDAsyslib.lib 


Adds all modules from the library file syslib.lib. 


a 
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REPLACE 


4.4.4 REPLACE — Replaces modules. 


“Format Name REPLACE ~~ ~—~—<Option_—_—‘Subcommand 


Yes Yes 


Parameters Option <Object module file name> 


<Relocatable load module file name>} [,...] 


<Library file name> 
Sebcommand <Object module file name> 
<Relocatable load module file name> | | 
<Library file name>[(<module name>[,...])] 
Function Substitutes modules in a specified file for modules of the same name in the 


library file being edited. 


Explanation (1) When a module in the library file being edited has the same name as a module 


in the specified file, the former is replaced by the latter. If there is no module 
with the same name in the library file being edited, the module is simply 
added as with the ADD option or subcommand. 

(2) When only a file name is specified, if no file type is specified, the type is 
assumed to be .obj. When a module name is specified after a file name, the 
file is assumed to be a library file, so if no file type is specified, the type is 
assumed to be .lib. 

(3) To substitute only certain modules from a library file, specify the module 
names after the library file name. Up to 10 module names may be specified. 
However, module names cannot be included when REPLACE is specified as 
an option. 

EXAMPLE: REPLACE Ibf (m1,m2,m3) 


A A Module names 


Library file name 
(4) When modules in library files are specified, the specified module names are 
sorted in alphabetical order and modules are replaced in that order. They are 
not replaced in the order in which specified. 
EXAMPLE: REPLACE lbf (e, a, d, c, b) 
5, 1, 4, 3, 2 ...Order of replacement 


(Continued on next page) 
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Explanation 
(cont) 


(5) 


(6) 


(7) 


(8) 


(9) 


When the names of modules in a library file are not specified, all modules in 
the file are substituted. 


EXAMPLE: REPLACE lbf.lib 


A tinea file name 


The name of an object module or relocatable load module is the name defined 
in the module. The LIST option or subcommand is a convenient way of 
confirming which modules are stored in a library file. 

REPLACE cannot be used together with EXTRACT or OUTPUT options or 
subcommands. 

The following cases will result in error, and the parameters after the error 
position will not be processed. 

(a) A specified file does not exist. 

(b) A specified module does not exist in a library file. 

(c) The content of the specified file is invalid. 

(d) |The number of modules to be stored exceeds 32,767. 

(€) | Memory capacity is insufficient for the substitution to be performed. 
(f) | The number of input files exceeds 12. 

The process of replacing a module involves deleting the module of the same 
name in the library file being edited, then inputting the module from the file 
specified by the REPLACE option or subcommand and storing it in the library 
file. The following special caution is thus required: If a module to be 
substituted contains an extemally defined symbol already defined in another 
module in the library file, the old module will be deleted, but the replacement 
module will not be stored. 


(Continued on next page) 
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Examples —REPLACE=userlib.lib 
All modules in the library file userlib.lib are stored in the library file being 
edited, replacing modules with the same name. 


REPLACEAloadx.rel,loady.rel 
The two modules in the relocatable load module files loadx.rel and 


loady.rel are substituted for modules of the same name in the library file 
being edited. 


REPLACEAdatax(member),omf 
The module named member in library file datax.lib, and the module in the 
object module file omf.obj, are substituted for modules of the same name in 
the library file being edited. 
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4.4.5 DELETE — Deletes modules. 


Format Name DELETE Option Subcommand 
Yes Yes 


Parameters <Module name> [....] 


Function Deletes specified modules from the library file being edited. 


Explanation (1) If a specified module does not exist in the library file, an error occurs, and the 
parameters after the error occurrence are not processed. 

(2) The name of an object module or relocatable load module is the name defined 
in the module. The LIST option or subcommand is a convenient way of 
confirming which modules are stored in a library file. 

(3) DELETE cannot be used together with EXTRACT or OUTPUT options or 
subcommands. 


Examples —DELETE=inchar,outchar 
Deletes the two modules inchar and outchar. 


DELETEAdatatbl,sort 
Deletes the two modules datatbl and sort. 
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EXTRACT 


4.4.6 EXTRACT — Extracts modules. 


Format Name EXTRACT Option Subcommand 


Parameters <Module name> [....] 


Function Extracts specified modules from the library file being edited. 


Explanation (1) The extracted modules are output in library file format with the file name 
specified by the OUTPUT option or subcommand. 

(2) The name of an object module or relocatable load module is the name defined 
in the module. The LIST option or subcommand is a convenient way of 
confirming which modules are stored in a library file. 

(3) Ifa specified module does not exist in the library file, an error occurs, and the 
parameters after the error occurrence are not processed. 

(4) EXTRACT cannot be used together with the CREATE, ADD, DELETE or 
REPLACE options or subcommands. 


Examples —-EXTRACT=add,sub,mul,div 


Extracts the four modules add, sub, mul, and div from the library file being 
edited. 


EXTRACTAalpha,upper, lower,digit,cntrl 


Extracts the five modules alpha, upper, lower, digit, and cntrl from the library 
file being edited. 
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END 


4.4.7 END — Specifies end of subcommand input. 


Format Name END Option Subcommand 
No Yes 


Parameters None 


Function Outputs a newly created or updated library file. 


Explanation (1) When more than one library file is edited in one Librarian execution, the 
editing of each library file is terminated by an END subcommand. 
(2) Specification of the END subcommand causes the Librarian to output the 
edited library file. If, however, the number of modules stored in the library 
file is zero, the library file is not created or updated. 


Examples END 
Outputs a library file. 
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4.4.8 EXIT — Specifies end of Librarian operations. 


Format Name EXIT Option Subcommand 
No Yes 


Parameters None 


Function Terminates Librarian operations. 


Explanation (1) The EXIT subcommand is used to terminate a set of Librarian operations 
executed by the subcommand specification. 

(2) When executing from a subcommand file, all subcommands following after an 
EXIT subcommand are ignored. If the EXIT subcommand is not specified, 

a warning message will be displayed. 

(3) When the EXIT subcommand is used, the immediately preceding END 
subcommand may be omitted. In that case the EXIT subcommand serves also 
as an END subcomman4d, causing the library file to be output before 
terminating the Librarian operation. 


Examples EXIT 
Terminates Librarian operations. 


30 


HITACHI 


4.4.9 ABORT — Aborts Librarian operations. 


Format Name ABORT Option Subcommand 
No Yes 


Parameters None 


Function Aborts Librarian operations. 


Explanation (1) When executing by the subcommand specification, the ABORT subcommand 
can be used to abort editing operations. 

(2) When the ABORT subcommand is specified, the library file being edited will 
not be created or updated. If, however, a list file was output by a LIST 
subcommand before the ABORT subcommand, the list file will remain 
unchanged. 


Examples ABORT 
Aborts Librarian operations. 
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4.5 List Display 


4.5.1 LIST — Displays contents of a library file. 


Format Name LIST Option Subcommand 
Yes Yes 
Parameters Option [<List file name>] 
Subcommand {[<List file name>][(S)}] 
Function Outputs a list of the contents of the library file being edited to the 


Explanation (1) 


(2) 


(3) 


(4) 


(5) 


(6) 


standard output device or to a file. 


The names of modules stored in the library file, export symbol names, and 
other information is output on a list. For the list format, see section 6.2, 
Librarian Lists. 

When no list file name is specified, the list is output to the standard output 
device. 

When a list file name is specified, the list is output to a file. Specify a new list 
file name; the list cannot be appended to an existing file. If an existing file is 
specified, the existing file contents will be replaced. 

When no file type is specified as part of the list file name, the type is assumed 
to be .Ist. 

To obtain a list of export symbols designated in modules, specify the (S) 
parameter. If the (S) parameter is not specified, only the module names will 
be listed. The (S) parameter cannot be included when LIST is specified as an 
option. 

The LIST option or subcommand may be specified any number of times 
during the editing process. The library file contents at the point of 
specification will be listed. 


(Continued on next page) 
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Examples -LIST 
A list is output to the standard output device. 
Export symbols are not shown. 


LIST 
A list is output to the standard output device. 


Export symbols are not shown. 


LISTAlibx(S) 
A list including export symbols is output to a file named libx.|st. 
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Section 5. Input to the Librarian 


5.1 Object Module Files 


Object module files output from a C compiler or assembler can be input to the Librarian and stored 
as modules in library files. 


5.2 Relocatable Load Module Files 


A relocatable load module file output from the Linkage Editor can be input and stored in a library 
file as one module. 


5.3 Library Files 


The Librarian inputs the library file it is editing. Also, modules to be stored in this library file can 
be input from other library files. Either specified modules can be input, or all the modules in a 
library file can be input at one time. 


Input can be made only from library files created using this Librarian. 
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Section 6. Output from the Librarian 
6.1 Library Files 


The Librarian can combine two or more modules into a single output library file. It can also update 
an existing library file, or extract modules from an existing library file, and output the result in 
library file format. 


6.2 Librarian Lists 


When the LIST option or subcommand is specified, a list of the library file contents is output to the 
standard output device or to a file. The format of a librarian list is shown in Figure 6-1. 


Library file name: 
(1) 
Attribute: __(2) Creator: (11) 
Number of modules: _ (3) _ Creation date: (5) 
Number of symbols: _ (4) _ Revision date: (6) 
7) _(8)_ —_ Entry date: (9) 
(10) (10) 


() (8) Entry date: (9) 


Figure 6-1. Librarian List Format 


(1) Shows the library file name. If the name is too long to fit on one line it is continued to the next 
line. When modules are extracted from an existing library file, the list shows the contents of the 
existing library file. 


(2) Shows the library file attribute. 
SYSTEM ie System library 
USER ees User library 


(3) Shows the total number of modules stored in the library file, in decimal notation. 


(4) Shows the total number of externally defined symbols in the library file, in decimal notation. 
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(5) Shows the date and time of library file creation. This information is given in the following 
format. 


dd - mmm - yy hh: mm: ss 


second 

minute 

hour 

year (last 2 digits) 
month (3 letters) 
day 


(6) Shows the date and time of the most recent library file update. In the case of library files 
newly created using the CREATE option or subcomman4d, this is the same as the date of 
creation. The format is the same as for the creation date, above. 


(7) Shows the names of modules stored in the library file, in alphabetical order. 


(8) Shows the kind of editing operation performed on the module. 


BLANK _.... a module stored in an existing library file 
(A) ... an added module 

(R) ... a replacement module 

(E) .-. an extracted module 


Modules deleted by means of the DELETE option or subcommand are not listed. 


(9) Shows the date and time a module was stored in the library file. The format is the same as for 
the library file creation date and revision date. 


(10) When the (S) parameter is specified with the LIST subcommand, the export symbols in each 
module are shown. These symbol names are listed in alphabetical order two on each line. 


An example of a list when the (S) parameter is specified with the LIST subcommand is given in 
Figure 6-2. Figure 6-3 shows a list without the (S) specification. 


MS-DOS system: 
(11) Shows the name of the tool used to create the library file (Librarian model). If the name is 
longer than 40 characters, only the first 40 characters are shown. 
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Library filename: _clib.lib 
Attribute: USER 
Number of modules: 6 Creation date: 08-Jan-90 14:18:47 
Number of symbols: 6 Revision date: 01-Mar-90 19:56:33 


Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
_ALOCBUF (A) Entry date: 01-Mar-90 19:56:33 
_alcobuf 


_DIVI (A) Entry date: 01-Mar-90 19:56:33 
divi 


Figure 6-2. Librarian List (with (S) specification) 


Library file name: clib.lib 

Attribute: USER 

Number of modules: 6 Creation date: . 08-Jan-90 14:18:47 
Number of symbols: 6 Revision date: 01-Mar-90 19:56:33 


Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
Entry date: 08-Jan-90 14:18:47 
_ALOCBUF (A) Entry date: 01-Mar-90 19:56:33 
_DIVI (A) Entry date: 01-Mar-90 19:56:33 


Figure 6-3. Librarian List (no (S) specification) 
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6.3 Console Messages 
The Librarian displays the following messages on the standard output device. 
Opening Message: Displayed when the librarian command is input. 
H SERIES OBJECT LIBRARIAN Ver. 1.2B 
Copyright (C) Hitachi, Ltd. 198X 
Licensed Material of Hitachi, Ltd. 
Normal Completion Message: Displayed when library file editing has ended normally. 


OBJECT LIBRARIAN COMPLETED 


Abort Message: Displayed when the library file editing is aborted by either an error or an ABORT 
subcommand. 


OBJECT LIBRARIAN ABORT 


Subcommand Prompt: Indicates that the Librarian is in subcommand input wait state during 
interactive execution. 


Subcommand Continuation Symbol: Request for a continuation line, when continuation of a 
subcommand is specified during interactive execution. 
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Section 7. Error Messages 


The Librarian outputs error messages in the following form. 


** <Error number> <Error message> [(<Additional information>)] 


Error number: The first digit indicates the level of the error. (xx represents the second and 
third digits.) 
1xx : Warning Processing of a particular module is skipped. 
2xx : Error If started by input from the command line or a 


subcommand file, processing is stopped. In 
interactive mode, processing of the subcommand is 
stopped when the error is detected, and a prompt is 
displayed for the next subcommand. 


3xx : Fatal error Processing is stopped. 
A list of error messages is given below in Tables 7-1, 7-2 and 7-3, in the following format. 


Error number Error message Additional information 

Description of error 

Corrective action, etc. 

Note: Additional information includes the name of the file in which the error occurred, or the 
module name or symbol name. In the list of errors, --- means that no additional 
information is given. 
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Table 7-1. List of Warning Messages 


101 DUPLICATE MODULE Module name 
An attempt was made to add a module already stored in the library file. 
Processing of the module is skipped. : 
102 DUPLICATE SYMBOL - Module Symbol 
name cad name 
An attempt was made to add an export symbol already present in the library file. 
Processing of the module is skipped. 
103 MODULE NAME TOO LONG Module name 
- ALLOWED UP TO 32 
A module name of more than 32 characters was specified. 


The name is valid up to the 32nd character. The rest is ignored. 
104 EXIT SUBCOMMAND NOT --- 
FOUND - ASSUMED 
No EXIT subcommand was specified. 
Processing continues as though an EXIT subcommand had been specified. 
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Table 7-2. List of Error Messages 


201 INVALID SUBCOMMAND/OPTION --- 
The option or subcommand specified is invalid in this context. 


Specify a valid option or subcommand. 
202 SYNTAX ERROR --- 
Syntax of the specified option or subcommand is incorrect. 
Check the syntax and re-specify the option or subcommand. 
203 SUBCOMMAND LINE LENGTH --- 
TOO LONG 
Length of the subcommand entry exceeds 128 characters. 


Re-specify, keeping the length within 128 characters. 


204 CONFLICTING SUBCOMMAND --- 
Subcommands are specified in the wrong order, or an illegal combination of subcommands is 


specified. 


Check the order of subcommands and re-specify. 
205 ILLEGAL FILE NAME --- 
The specified file name is not valid. 


Specify a correct file name. 
206 ILLEGAL MODULE NAME --- 
The specified module name is not valid. 


Specify a correct module name. 
207 MODULE NOT FOUND Module name 
The specified module cannot be found. 


“Check the name of the module, then re-specify. 


(Continued on next page) 
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Table 7-2. List of Error Messages (cont) 


208 MISSING OUTPUT FILE NAME os 
No output file was specified with an EXTRACT option or subcommand. 
Use the OUTPUT option or subcommand to specify an output file. 

209 TOO MANY INPUT FILES --- 


More than 12 input files were specified for input at the same time. 


First output the library file, then re-input the library file and input the remaining files. 
210 TOO MANY MODULES --- 


The number of modules exceeds the allowable number. 


No more modules can be stored in the library file now being created or edited. Store any 
additional modules in a separate library file. 
211 TOO MANY SYMBOLS --- 


The number of symbols exceeds the allowable number. 


The library file now being created or edited cannot contain any more symbols. Modules with 
additional symbols must be stored in a separate library file. 
212 ILLEGAL FILE FORMAT --- 


The specified file format is incorrect. 


Check the file contents and re-execute. 
213. MEMORY OVERFLOW zs 


There is no space remaining in the Librarian's usable memory. 


Obtain additional memory and re-execute. 
214 FILE NOT FOUND File name 
The specified file cannot be found. 


Check the directory and the specified file name, then re-specify. 


(Continued on next page) 
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Table 7-3. List of Fatal Error Messages 


301 INVALID COMMAND PARAMETER --- 


An improper command parameter was specified. 


Check the command parameters and re-execute. 
302 CONFLICTING OPTION --- 
There is a contradiction among different options specified. 


Check the order of option specification, then re-specify. 

303 CANNOT OPEN FILE File name 
File cannot be opened, or the CREATE or OUTPUT option or subcommand specified an 
already existing file. 


Check the specified file name. If the file name is correct, the disk may be 
full, or there may be a disk hardware error. Check the problem, then re-execute. 
If an existing file was specified by the CREATE or OUTPUT option or subcommand, 
delete the existing file, then re-execute. 
304. CANNOT INPUT FILE File name 


File cannot be input. 


Check the specified file name. If the file name is correct, there may be 
a disk hardware error. Check the problem, then re-execute. 
305 CANNOT OUTPUT FILE File name 
File cannot be output. 
Check the specified file name. If the file name is correct, the disk may be 


full, or there may be a disk hardware error. Check the problem, then re-execute. 


306 CANNOT CLOSE FILE File name 
File cannot be closed. 
Check the specified file name. If the file name is correct, the disk may be 
full, or there may be a disk hardware error. Check the problem, then re-execute. 


Note: The Librarian uses temporary files with names in the format shown below. These 
temporary file names may appear as additional information in error messages. 


Annnnn. TEMP 


5 digits, decimal 
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Section 8. Restirictions 


Restriction on the Librarian are shown in Table 8-1. If the numerical restrictions are exceeded, 


Librarian operations will not execute correctly. 


Table 8-1. Restrictions on Librarian Processing 


No. 


1 


3 


9 
10 


Item Limits 

The number of modules Max. 32,767 
that can be storedina 

library file 

The number of symbols = Max. 65,535 


that can be present ina 
library file 
The number of input files Max.12 


The number of modules 
that can be specified ina 


Max. 10 


library file 


Depends on OS 


Length of option or 
subcommand 


Length of file name 


Max. 128 characters 


Max. 128 characters Includes default file-type 


Max. 32 characters 


Length of symbol name 


Max. 32 characters 


Input file formats * Object module file output by 


assembler or C compiler. 


+ Relocatable load module file. 


* Library file created using this 


Librarian. 
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Remarks 

Assumes that the system on which 
Librarian runs has adequate 
memory. 


Total number of files specified by 
LIBRARY, ADD, or REPLACE not 
including subcommand files. 
When specifying a library file with 
ADD or REPLACE 


Length of command line 


Not including (RET) 


characters. File name format 
depends on OS. 


Length of module name 


Appendix A Examples of Use of Librarian 


A.1 Librarian Execution by Command Line 


% 


IbrA-CREATE=func-ADD=abs,mod,sqrt,exp,log (RET. 


-~(1) Creation 
“~~ 
1 2 
% \brAfunc-ADD=sin,cos-DELETE=abs,mod-LIST (RET) (2) Editing 
YN 
3 4 5 6 
% \brAfunc-EXTRACT=sqrt,exp-OUTPUT=newfnce (3) Extraction 


7 8 9 


. The CREATE option at the beginning of the option line is specified to create a new 


library file. 


. The file names for the modules to be entered are specified using the ADD option. 


3. The name of the library file to be edited is specified. 


ym ID 


. The file names for modules to be added to the existing library file are specified using 


the ADD option. 


. The names of the modules to be deleted from the existing library file are specified using 


the DELETE option. 


. The LIST option is specified to confirm the editing results. 
. An existing library file from which modules are to be extracted is specified. 


The names of the modules to be extracted are specified using the EXTRACT option. 
The name of a new library file to which the extracted modules are to be output is specified 
using the OUTPUT option. 


This process is illustrated in Figure A-1. 
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func.lid newfnc.lib 


File name 


Module name 


Figure A-1. Results of Librarian Execution by Command Line 
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A.2 Librarian Execution by Subcommands 


% 


AVS & 


Ibr (RET) 

CREATEAfunc (RET) 
ADDAsart,exp,log,sin,cos (RET) 

END 

LIBRARY Afunc (RET) 
REPLACEAsin.new,cos.new,tan.new (RET) 
END (RET) 

LIBRARYAfunc 

LIST 

EXTRACTAsqrt,exp (RET) 10 (3) Extraction 
OUTPUTAnewfnc (RET) tl 

END (RET) wl 


EXIT (RET) awkS 


(1) Creation 


(2) Editing 


i. 4 of bf # By 
COIN AWE WY NH 


The Librarian is started. 

The CREATE subcommand at the beginning of the option line is specified in order to create a 
new library file. 

The file names of modules to be loaded are specified using the ADD subcommand. 

The END subcommand is specified to terminate the creation process. 

The name of the library file to be edited is specified. 

Modules in the existing library file are replaced, using the REPLACE subcommand. The file 
names of the modules to be replaced is specified. 

The END subcommand is specified to terminate the editing process. 

An existing library file is designated for extraction of modules. 

The LIST subcommand is specified to confirm the contents of the existing library file. 

The names of the modules to be extracted are specified using the EXTRACT subcommand. 
The name of a new library file to which the extracted modules are to be output is specified 
using the OUTPUT subcommand. 

The END subcommand is specified to terminate the extraction process. 

The EXIT subcommand is specified to terminate the Librarian program. 


This process is illustrated in Figure A-2. 
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sqrt.obj func.lib func.lib 


sqrt 


exp.obj 


newinc.lib 


exp 


sin.new 


File name Be tan.new 


Module name —>( =» ( 


Figure A-2. Results of Librarian Execution by Subcommand 
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